Running Lua programs on z/OS
To run a Lua program, use the Lua stand-alone interpreter. z/OS-specific details are described here.
MVS versus z/OS UNIX
Lua4z includes two versions of the Lua interpreter:
- A version for running Lua programs on z/OS UNIX
- A version for running Lua programs on MVS (including TSO/E)
The z/OS UNIX version is installed in a z/OS UNIX directory. The features of the Lua interpreter on z/OS UNIX match the features on other, non-z/OS platforms.
The MVS version is installed in an MVS program library that might have been added to the LINKLIST concatenation. The MVS version of the Lua interpreter introduces the following features:
- LUA ddname
- LUACONF member
The name of the Lua program that you specify to the MVS version of the Lua interpreter can be the name of a member in an MVS data set (PDS or library). That data set must belong to the concatenation specified by the LUA ddname.
In TSO/E (including ISPF), you would typically define the LUA ddname in your TSO/E logon procedure. For example:
//LUA DD DISP=SHR,DSN=&SYSUID..LUA
You can also allocate the LUA ddname dynamically in TSO/E. For example, suppose you want to run the Lua program MYID.LUA(HELLO), but the LUA ddname does not refer to MYID.LUA. You can enter the following TSO/E command to reallocate the ddname:
ALLOC F(LUA) DA('MYID.LUA') SHR REUSE
and then enter the following command to run the program:
If a member named LUACONF exists in the LUA ddname concatenation, then the MVS version of the Lua interpreter uses that member to set the values of the LIBPATH, LUA_CPATH, and LUA_PATH environment variables.
For information about how Lua uses the LUA_CPATH and LUA_PATH variables, see the Lua Reference Manual.
The LIBPATH variable is not specific to Lua. LIBPATH is the z/OS UNIX environment variable that defines the dynamic link library (DLL) search path. LIBPATH must refer to the Lua4z lib directory that contains liblua.so, which is the shared object file that contains the Lua standard libraries. (Lua programs running on MVS use the LIBLUA load module stored in the same MVS data set as the interpreter load module, LUA.)
The contents of LUACONF has the following format:
LUA_HOME = "value" LIBPATH = "value" LUA_CPATH = "value" LUA_PATH = "value"
where each line is optional.
LUA_HOME is not an environment variable; it is a special variable that you can specify in LUACONF as a shortcut for defining LIBPATH, LUA_CPATH, and LUA_PATH.
If you specify LUA_HOME, any other definitions in LUACONF are ignored.
Specifying the following single line in LUACONF:
LUA_HOME = "home"
is equivalent to specifying the following lines:
LIBPATH = "home/lib" LUA_CPATH = "./?.so;" .. "home/lib/lua/5.1/?.so;" .. "home/lib/lua/5.1/loadall.so;" .. "//?" LUA_PATH = "./?.lua;" .. "home/share/lua/5.1/?.lua;" .. "home/share/lua/5.1/?/init.lua;" .. "home/lib/lua/5.1/?.lua;" .. "home/lib/lua/5.1/?/init.lua;\" .. "//DD:LUA(?)"
Lua4z initializes the LIBPATH, LUA_CPATH, and LUA_PATH variables in LUACONF with the following default values that refer to
LIBPATH = "/usr/local/lib" LUA_CPATH = "./?.so;" .. "/usr/local/lib/lua/5.1/?.so;" .. "/usr/local/lib/lua/5.1/loadall.so;" .. "//?" LUA_PATH = "./?.lua;" .. "/usr/local/share/lua/5.1/?.lua;" .. "/usr/local/share/lua/5.1/?/init.lua;" .. "/usr/local/lib/lua/5.1/?.lua;" .. "/usr/local/lib/lua/5.1/?/init.lua;" .. "//DD:LUA(?)"
You can use the Lua string concatenation operator to prepend or append to these default values. For example:
LIBPATH = LIBPATH .. ":/u/myid/lib"
is equivalent to:
LIBPATH = "/usr/local/lib:/u/myid/lib"
To check the values of these environment variables in a running Lua program, run paths.lua supplied in the Lua4z examples directory.
Lua4z (both the MVS and z/OS UNIX versions of the Lua interpreter) works with Lua programs encoded using EBCDIC code page 1047 or 037.
Lua4z includes code to tolerate square brackets that are encoded using EBCDIC code page 037. Rather than rejecting 037-encoded square brackets as garbled input, Lua4z interprets them as square brackets.
Consider configuring your 3270 terminal emulator to use host code page 1047 rather than 037. (Although you might have a specific reason for using 037, which is why Lua4z tolerates square brackets encoded in that code page.)
Member in the LUA ddname concatenation
Suppose you have a member named MYID.LUA(HELLO) containing the following Lua program:
where the MYID.LUA library is in the LUA ddname concatenation.
To run the Lua program in TSO/E foreground, enter the following command at a TSO/E or ISPF command prompt:
MVS data set not in the LUA ddname
To run a Lua program that is stored in an MVS data set that is not in the LUA ddname concatenation, specify two slashes, then the fully qualified data set name enclosed in single quotation marks, all enclosed in double quotation marks:
z/OS UNIX file
To run a Lua program that is stored in a z/OS UNIX file, specify the absolute path of the Lua program in quotation marks:
If your Lua program uses POSIX functions, enter
LUAP instead of
LUAP invokes the Lua interpreter with the Language Environment runtime option
To start the Lua interpreter in interactive mode, enter
LUAP without any parameters.
To exit interactive mode, either:
- Press the System Attention key
The following JCL runs the Lua program MYID.LUA(HELLO):
/MYLUA JOB job card details //LUA EXEC PGM=LUA,PARMDD=SYSIN //SYSPRINT DD SYSOUT=* //LUA DD DISP=SHR,DSN=MYID.LUA //SYSIN DD * hello /*
If your program has particular runtime requirements, then you can specify Language Environment runtime options before the Lua program name, separated by a slash.
For example, if your program uses POSIX functions, specify
posix(on) / hello -n 1234 //lua(config)
In the previous example,
-n 1234 //lua(config) are arguments to the Lua program, where
//lua(config) is a member
in the LUA ddname concatenation. In this example, since the LUA ddname in the JCL specifies only one data set,
refers to the member MYID.LUA(CONFIG).
The previous JCL assumes that the program library that contains the Lua interpreter is in the LINKLIST concatenation, as described in the Lua4z installation instructions. If the Lua interpreter is not in LINKLIST, you need to specify its program library in the STEPLIB ddname:
//STEPLIB DD DISP=SHR,DSN=SYS1.LUA4Z.LOADLIB
z/OS UNIX dependencies when running on MVS
No z/OS UNIX dependencies when using standard libraries only
If you run a Lua program on MVS (for example, in an MVS batch job or from an ISPF command prompt) and that program uses only the core Lua programming language and standard libraries, then there are no dependencies on z/OS UNIX files. The Lua program relies on the MVS version of the Lua interpreter and standard libraries that are installed in an MVS data set.
In this case:
LIBPATH is not relevant because the MVS version of the Lua interpreter does not need that variable to find the MVS load library member LIBLUA; that member is in the same MVS data set as the interpreter.
LUA_CPATH is not relevant because the
requirefunction does not need to find any .so files.
The LUA_PATH environment variable is relevant only if your Lua program uses the
requirefunction to refer to another Lua program.
z/OS UNIX dependencies when using Lua extensions
If you run a Lua program on MVS and that program uses any of the Lua extensions included with Lua4z, then you need files that are stored in the z/OS UNIX file system. Specifically, shared object (.so) files supplied in the Lua4z lib directory, Lua program (.lua) files supplied in the Lua4z share directory, or both, according to each Lua extension. Furthermore, the Lua extension .so files refer to the liblua.so file on z/OS UNIX, not the MVS load library member LIBLUA that is used by the running MVS version of the Lua interpreter.
In this case:
LIBPATH must refer to the Lua4z lib directory because it contains liblua.so.
LUA_CPATH must refer to the Lua extension .so files supplied in the Lua4z lib/lua/5.1 directory.
The LUA_PATH environment variable must refer to the Lua extension .lua files supplied in the Lua4z share/lua/5.1 directory.
To make a Lua program an executable UNIX program, use
chmod +x and add the following shebang line to the start of the program:
/usr/local/bin/lua is the location of the Lua interpreter.