Lua4z
A binary distribution of Lua for z/OS, with batteries

Module ispf

ISPF support for Lua.

Functions

bind (parms) Binds a table of Lua variables to ISPF dialog variables.
edit (dsn) Edits a data set using the ISPF editor.
view (dsn) Manipulates the contents of a data set without saving changes.
get (namelist, pool) Retrieves variables from a pool or profile or system symbol.
put (namelist, pool) Updates variables in the shared or profile pool.
getToken () Returns a tokenized 8-character name in the form Lnnnnnnn.
unbind () Unbinds a Lua table from the ISPF variable pool.

Functions

bind (parms)
Binds a table of Lua variables to ISPF dialog variables. This function calls the VDEFINE z/OS ISPF service.

Parameters:

  • parms The list of variables to bind: their names, types, and, for character variables, length.

    You can specify parms either as a string or as a table.

    The string format has the following syntax:

    "name(char(length)|length|double|int|float) ..."

    where:

    name is the name of an ISPF dialog variable

    char, double, int, or float specify the type of the variable

    length is an integer that specifies the length of a character data variable

    name(length) is shorthand for name(char(length))

    The table format has the following syntax:

     {
   {"name", "type", length}, ...
 }

    where:

    type is char, double, int, or float

    length applies only to type char

    The variable types that you specify in parms correspond to the following VDEFINE formats and lengths:

    How type maps to VDEFINE
    ispf.bind type VDEFINE format and length
    char CHAR format with specified length
    double FLOAT format with length 8
    int FIXED format with length 4 (signed integer)
    float FLOAT format with length 4

Returns:

    A table consisting of fields that correspond to each of the bound variables. Note that, unlike the ISPF dialog variable names, these field names are case-sensitive. For example, if you specified a variable name in lowercase in the input parm, then the corresponding field name in the returned table is also in lowercase.

Usage:

     -- Creates an ISPF table, adds rows, and then prints the rows

 local ispf = require("ispf")
 local ispexec = ispf.ispexec

 -- Bind ISPF dialog variables NUM, NAME, and ADDR
 -- using table format of ispf.bind function
 local row = ispf.bind {
   { "num", "int" },
   { "name", "char", 20 },
   { "addr", "char", 60 }
 }
 -- Equivalent bind function call using string format:
 -- local row = ispf.bind "num(int) name(20) addr(60)"

 -- Example names
 local names = {
   "Alfa", "Bravo", "Charlie", "Delta", "Echo",
   "Foxtrot", "Golf", "Hotel", "India", "Juliett"
 }

 -- Create an ISPF table containing
 -- the variables NUM, NAME, and ADDR
 ispexec("TBCREATE TAB1 NAMES(NUM,NAME,ADDR) NOWRITE REPLACE")

 for i = 1, 10 do
   -- Set the values of the ISPF dialog variables
   row.num  = i
   row.name = names[i] .. " Corporation"
   row.addr = i .. " Brodie-Hall Drive"
   -- Add a table row using these values
   ispexec("TBADD TAB1")
 end

 -- Set the row pointer to the top of the table
 ispexec("TBTOP TAB1")

 -- Iterate over the table rows
 while (ispexec("TBSKIP TAB1") == 0) do
   print(row.num, row.name, row.addr)
 end

 -- Close the table without saving it
 ispexec("TBEND TAB1")
edit (dsn)
Edits a data set using the ISPF editor.

This function calls the EDIT z/OS ISPF service.

Parameters:

  • dsn string The data set name to edit.

Returns:

    The return code from the ISPF EDIT service
view (dsn)
Manipulates the contents of a data set without saving changes.

This function calls the VIEW z/OS ISPF service.

Parameters:

  • dsn string The data set name to view.

Returns:

    The return code from the ISPF VIEW service
get (namelist, pool)
Retrieves variables from a pool or profile or system symbol.

This function calls the VGET z/OS ISPF service.

Parameters:

  • namelist string The names of one or more dialog variables whose values are to be copied from the shared or profile pool to the function pool.
  • pool string The variable pool where the variable resides: "SHARED", "PROFILE", or "ASIS". Default is "ASIS")

Returns:

    The return code from the ISPF VGET service.
put (namelist, pool)
Updates variables in the shared or profile pool.

This function calls the VPUT z/OS ISPF service.

Parameters:

  • namelist the names of one or more dialog variables whose values are to be copied from the function pool to the shared or profile pool.
  • pool string the variable pool to copy to: "SHARED", "PROFILE", or "ASIS". Default is "ASIS"

Returns:

    The return code from the ISPF VPUT service.
getToken ()
Returns a tokenized 8-character name in the form Lnnnnnnn. This is useful for creating temporary ISPF table names or ddnames.
unbind ()
Unbinds a Lua table from the ISPF variable pool.

This function releases variables previously bound with the bind function.

This function calls the VDELETE z/OS ISPF service for each field in the table.

Typically, there is no need to call unbind explicitly; it is implicitly called by garbage collection.

However, calling unbind explicitly is useful in cases where the same ISPF variable has been bound to more than one Lua table in the same scope, and so garbage collection has not been invoked. In this case, be careful to unbind tables in reverse order; start by unbinding the most recently bound table. Calling unbind in the wrong order on tables that refer to the same variable can cause errors or undefined behavior.

Usage:

     local ispf = require("ispf")

 local ztimelFormat = "hh:mm:ss:TQ"
 local ztimelLength = string.len(ztimelFormat)
 local ztimelDef = {
   { "ztimel", "char", ztimelLength }
 }

 local function getTime()
   ispf.ispexec("VGET ZTIMEL")
 end

 local function wait(secs)
   secs = secs or 2
   print("Wait " .. secs .. " seconds...")
   os.sleep(secs)
 end

 local function reportTime(tableName, time, msg)
   msg = msg or ""
   print("Time reported by " .. tableName .. ": " ..
     time .. msg)
 end

 -- Bind ISPF dialog variable
 local sysvar1 = ispf.bind(ztimelDef)

 getTime()

 reportTime("sysvar1", sysvar1.ztimel)

 -- Bind same ISPF dialog variable
 local sysvar2 = ispf.bind(ztimelDef)

 wait()

 getTime()

 reportTime("sysvar2", sysvar2.ztimel)
 reportTime("sysvar1", sysvar1.ztimel, " - not updated!")

 sysvar2:unbind()
 print("After unbinding sysvar2...")

 wait()

 getTime()

 reportTime("sysvar1", sysvar1.ztimel)