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.
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
, orfloat
specify the type of the variablelength is an integer that specifies the length of a character data variable
name(length)
is shorthand forname(char(length))
The table format has the following syntax:
{ {"name", "type", length}, ... }
where:
type is
char
,double
,int
, orfloat
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
typeVDEFINE
format and lengthchar
CHAR
format with specified lengthdouble
FLOAT
format with length 8int
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")
- parms
The list of variables to bind: their names, types, and, for character variables, length.
- edit (dsn)
-
Edits a data set using the ISPF editor.
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.
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.
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.
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.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. Callingunbind
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)