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

Running Lua programs on z/OS

To run a Lua program, use the Lua stand-alone interpreter. z/OS-specific details are described here. For platform-independent information about running Lua programs, see the Lua Reference Manual.

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

LUA ddname

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:

LUA HELLO

LUACONF member

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 /usr/local:

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.

Square brackets

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.) Character encoding issues are beyond this scope of this documentation, but the point is this: other language interpreters might expect 1047-encoded source, and reject 037-encoded square brackets as being garbled.

TSO/E foreground

Member in the LUA ddname concatenation

Suppose you have a member named MYID.LUA(HELLO) containing the following Lua program:

print("Hello, World!")

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:

LUA HELLO

You do not need to prefix LUA with TSO at an ISPF command prompt: the Lua4z installation procedure adds a LUA verb to an ISPF command table.

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:

LUA "//'HERID.LUA(HELLO)'"

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:

LUA "/usr/local/lua4z/doc/examples/hello.lua"

POSIX functions

If your Lua program uses POSIX functions, enter LUAP instead of LUA.

LUAP invokes the Lua interpreter with the Language Environment runtime option POSIX(ON).

Interactive mode

To start the Lua interpreter in interactive mode, enter LUA or LUAP without any parameters.

To exit interactive mode, either:

  • Enter os.exit()
  • Press the System Attention key

Batch

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):

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, //lua(config) 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 require function does not need to find any .so files.

  • The LUA_PATH environment variable is relevant only if your Lua program uses the require function 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.

z/OS UNIX

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

where /usr/local/bin/lua is the location of the Lua interpreter.