This chapter contains the following topics:
The user interface on an IBM i 6.1 system is completely menu-driven. The interface makes extensive use of function keys F1-F24.
Virtually every action performed via the menu has a command-line equivalent. Application executables, such as Oracle Tuxedo utilities, can be invoked from the command line using the call command. The call command has the following syntax:
call pgm parm(arg1 arg2 . . . )
The notion of the PATH and LD_LIBRARY_PATH environment variables in the UNIX shell is replaced by the library list. For example, the following command:
call hello parm('world')
is a request to search in the library list for the hello program. The first library in the library list that contains this program becomes the current library and the hello program is activated.
During this activation, if a service program (the IBM i 6.1 equivalent of a DLL or shared object) is needed, then the library list is searched again. The library list can be displayed with the dsplib
command, and manipulated with the addlible
and rmvlible
commands.
Jobs define execution context (roughly equivalent to a process). There are two kinds of jobs: interactive and batch. When a user signs on to a system, an interactive job is assigned to the new session. All call commands are executed inside this job. The wrkactjob
command lists all active jobs on the system. (It is equivalent to the ps
command on a UNIX system.) A batch job can be submitted via the sbmjob
command. The wrksbmjob
command lists all submitted batch jobs.
This section describes the two file systems that are important on an IBM i 6.1 platform: HFS and IFS.
HFS is the traditional flat file system. At the highest level it contains libraries. Each library may contain files, e.g., module files, program files, and physical files. A physical file, in turn, may contain members. All text files (including C program source code files) are stored as members of a physical file.
Executables may reside only in HFS, but symbolic links can be created from IFS to HFS via the addlnk
command.
HFS filenames are limited to ten characters and are not case sensitive.
IFS is a directory-oriented file system designed to support PC file-serving. IFS (especially /QOpenSys) closely resembles a UNIX file system.
Executables may reside only in HFS, but symbolic links can be created from IFS to HFS via the addlnk
command.
With one exception (/QOpenSys) filenames in IFS are case sensitive.
Separate commands must be used for HFS and IFS files:
wrklib
, wrkf
, and wrkmbrpdm
commands work only with HFS objects.cd
, mkdir
, dspcurdir
, and wrklnk
commands may be used with both IFS files and HFS files, but different syntax is required, depending on whether you are accessing HFS or IFS objects.cpytostmf
and cpyfrmstmf
commands are available for copying a text file from one type of file system to another. For example, the following command copies an IFS file called /QOpenSys/tuxedo/tmp/xyz
to an HFS physical file called tmp
in a member called xyz
(in a library called apps).cpyfrmstmf fromstmf('/QOpenSys/tuxedo/tmp/xyz') +
tombr('/qsys.lib/tmp.file/xyz.mbr') +
mbropt(*replace)
When you are working with ILE C programs in an HFS file system, you may redirect standard input, standard output, and standard error (the stdin
, stdout
, and stderr
files, respectively) by using the ovrdbf
command. See the CL Reference Manual for details.
There is no simple way to redirect standard IO and standard error messages to and from IFS files.
For example, to redirect stdout
of an ILE C program called prog
to an IFS file called /home/dougd/out
, enter the text shown in Listing 3-1.
ovrdbf file(stdout) tofile (tmplib/tmpfile) +
mbr (stdout)
call prog
cpytostmf frommbr +
('/qsys.lib/tmplib.lib/tmpfile.file/stdout.mbr') +
tostmf ('/home/dougd/out') stmfopt (*replace)
The make
, lex
, and yacc
utilities are not available on the IBM i 6.1. The native character set is EBCDIC, not ASCII.
Two Oracle Tuxedo commands, buildclient
and buildserver
, have been renamed buildclt
and buildsrvr
, respectively, in order to conform to the 10-character maximum.
The buildclt
and buildsrvr
commands accept input only for module files (*MODULE
), service program files (*SRVPGM
), binding directory (*BNDDIR
), and produce output program files (*PGM
). The ILE C modules must be produced by crtcmod
. Likewise, ILE COBOL modules must be produced by crtcblmod
.
The following example command lines show how to compile a C source file in member cx
of a file called tuxsrc
in a library called apps
. The object module is created in a file called cx in a library called apps
.
crtcmod module(apps/cx) srcfile(apps/tuxsrc) srcmbr(cx) +
sysifcopt(*ifsio) dbgview(*all) define('DEF=1')
Note that the special system interface option sysifcopt(*ifsio)
is specified here. This option allows the C runtime library to access IFS files. Because the Oracle Tuxedo system is compiled with this option, we strongly recommend using it for compatibility.
Note also that debugging has been turned on by dbgview(*all)
and the preprocessor defined for DEF has been set to 1. This is equivalent to specifying -DDEF=1 -g
on a cc
command line (on a UNIX platform).
Currently you cannot specify a C source file on the buildclt
or buildsrvr
command line.
The -f and -l options to the buildclt
and buildsrvr
commands also mean something slightly different from the same options to the equivalent commands (buildclient
and buildserver
) on a UNIX system.
On a UNIX platform, the -f (first) option allows you to specify a list of items to be passed to the cc
command such that the objects produced by running cc
on these items are linked before the Oracle Tuxedo libraries are linked.
The -l (last) option allows you to specify a list of items to be passed to the cc
command such that the objects produced by running cc
on these items are linked after the Oracle Tuxedo libraries are linked.
On an IBM i 6.1 platform the -f option accepts object modules (that is, files of type *MODULE) only, and the -l option accepts service programs (that is, files of type *SVRPGM) only.
The -B option allows you to specify a binding directory (*BNDDIR).
Consider the following example command line.
call buildclt ('-fapps/cx' '-fapps/cy' '-oapps/client')
This command accomplishes two tasks:
Consider the following example command line:
call buildsrvr ('-fapps/sx' '-fapps/sy' '-oapps/server' '-sSVC')
This command accomplishes two tasks:
If the -k
option of buildsrvr
is used, then the server main code is generated in member BSpid
of the tuxsrc
file in the qtemp
library, where the value of pid is the process ID of the buildsrvr
process. Because the qtemp
library is removed at the end of each job, you must make a copy of it in a permanent directory before signing off, if you want to keep it.
Both mkfldhdr
and viewc
generate header files in IFS, usually in the current directory. You must copy these .h
files into an HFS h file so the C compiler will be able to find them.
The mkfldhdr/ mkfldhdr32 -H
option creates a header file in HFS.
viewc
also generates the binary output file with a .VV
(instead of a .V
) suffix.
On the IBM i 6.1, the valid EDITOR environment variable values for tmconfig
command are "STRSEU
" and "EDTF
". If editing lines longer than 240 characters is required, please use EDTF
.
For the epifreg
command -f
option, the library name and service program name must be upper cased as shown in the following example:
call epifreg ('-r' '-p qa/fanatz1' '-i engine/security/authorization' '-o SYSTEM' '-v 1.0' '-f AAA101/FANATZ1' '-e qa_atz_entry')
.
There is a difference in IBM i 6.1 and UNIX. If the -C
option is specified, one COBOL copy file is created for each VIEW defined in the viewfile. These copy files are created in root directory (/), not in current directory like UNIX, unless an alternate directory is specified through the -d option.
Because of the 10 characters limit, all include files for Xerces-C++ Parser are located only in IFS. So the source code that includes those header files should be copied to IFS, and set INCLUDE
environment variable to $TUXDIR/include
before compiles. For an introduce to programming with Xerces-C++ , see the Xerces-C++ Version 2.8.0 Programming Guide.
If the XML buffer is encoded as EBCDIC characters, the encoding attribute should be set to "EBCDIC-CP-US".
Because of the 10 characters limit some others Tuxedo commands are changed on IBM i 6.1.
The Oracle Tuxedo system is distributed with a set of tools for manipulating the environment: getenv
, putenv
, setenv
, and env
.
IBM i 6.1 provides a single command, wrkenvvar
, that offers functionality similar to that available through getenv
, putenv
, setenv
, and env
. The wrkenvvar
command differs from the Oracle Tuxedo commands, however, in several aspects. First, unlike the distributed tools delivered with the Oracle Tuxedo system, wrkenvvar
cannot handle the expansion of variable names marked with a $ prefix (similar to shell variable expansion).
In addition, the hostname
and id
utilities are distributed only with the Oracle Tuxedo system:
hostname
command prints the name of the network node for the IBM i 6.1. The machine name used in the UBBCONFIG configuration file must match the name returned by hostname
.
All Oracle Tuxedo executables and header files are packaged in an HFS library (see tuxlib
during installation). Other data files (such as udataobj/*
and locale/C/*
) are placed in $TUXDIR
in IFS. $TUXDIR/bin
has symbolic links to HFS executables. $APPDIR
should also reside in IFS. You must add the HFS library to the library list before invoking any Oracle Tuxedo commands.
Assume tuxdir
is installed in /QOpenSys/tuxedo
, tuxlib
is installed as Tuxedo, and APPDIR
is set to /home/apps/simpapp
.
Begin by building the simpcl
and simpserv
programs (in Steps 1-9).
apps
.tuxsrc
.
crtsrcpf apps/tuxsrc rcdlen (120)
simpcl.c
from /qopensys/tuxedo/samples/atmi/simpapp
to tuxsrc simpcl
member.
cpyfrmstmf fromstmf('/qopensys/tuxedo/samples/atmi/simpapp/simpcl.c') +
tombr('/qsys.lib/apps.lib/tuxsrc.file/simpcl.mbr') +
mbropt(*replace)
crtcmod module(apps/simpcl) srcfile(apps/tuxsrc) +
srcmbr(simpcl) sysifcopt(*ifsio)
buildclt
.
call buildclt ('-fapps/simpcl' '-oapps/simpcl')
/qopensys/tuxedo/apps/simpapp
to member simpserv
of tuxsrc
.cpyfrmstmf fromstmf('/qopensys/tuxedo/samples/atmi/simpapp/simpserv.c') +
tombr('/qsys.lib/apps.lib/tuxsrc.file/simpserv.mbr') +
mbropt(*replace)
crtcmod module(apps/simpserv) srcfile(apps/tuxsrc) +
srcmbr(simpserv) sysifcopt(*ifsio)
buildsrvr
command.call buildsrvr ('-sTOUPPER' '-fapps/simpserv' '-oapps/simpserv')
/home/apps/simpapp/simpserv
to apps/simpserv
.addlnk obj('/qsys.lib/apps.lib/simpserv.pgm') +
newlink('/home/apps/simpapp/simpserv')
tuxlib
to the library list.addlible tuxedo
call putenv 'TUXDIR=/QOpenSys/tuxedo'
call putenv 'APPDIR=/home/apps/simpapp'
call putenv 'PATH=/QOpenSys/tuxedo/bin:/home/apps/simpapp'
call putenv 'TUXCONFIG=$APPDIR/tuxconfig'
call tmloadcf ('-y' 'UBB')
wrklnk
to verify that the file tuxconfig
has been created in /home/apps/simpapp
.call tmboot '-y'
Messages similar to those shown in Figure 3-2 are displayed.
Figure 3-3 shows the messages that are displayed.
To shut down an application, enter the following command.
call tmshutdown '-y'
Figure 3-5 shows the messages displayed during the shutdown process.
IBM ships a set of IPC tools as a PTF. These tools provide the functionality available on a UNIX system through the ipcs
and ipcrm
commands. There are some differences, however, the IBM tools have different names and produce output in a different manner.
To view the IPC resources consumed by all your applications, enter the following command.
call qp0zipcs
The output of qp0zipcs is generated in *QPRINT which means that it can be viewed as a spool file with the wrksplf
command.
To remove a particular IPC resource, such as a message queue ID (qid), enter the following command.
call qp0zipcr ('-qqid')
When an error occurs while you are running qp0zipcr, a message is generated in the joblog
. Use the dspjoblog
command to view it.
$APPDIR
is in /QOpenSys
.addlnk
command to create a symbolic link.) The IFS name must be identical to the HFS name; thus each IFS name is restricted to 10 characters.hostname
command.tlisten
command does not start itself in the background. To submit a batch job with tlisten
, use the sbmjob
command, for example:
Addenvvar envvar('TUXDIR') value('/QOpenSys/tuxedo')
SBMJOB CMD(CALL PGM(TLISTEN) PARM('-l' '//hostname:8899')) JOB(TLISTEN) CPYENVVAR(*YES).
SCANUNIT*2-1
value.tpusr
file is required for AUTHSVR
.
The threshold command parameter specified on the qmadmin qcreate
command line (such as the server RCMD), must refer to a symbolic link to an executable program in HFS. The link must be included in $PATH; typically it is found in $APPDIR.
UNIX shell scripts will not work here.
With Oracle Tuxedo 10g Release 3 (10.3), you can administer an Oracle Tuxedo application through any Web browser (such as Netscape or Internet Explorer) by using the Web-based GUI for administration. This section provides some tips for running the Oracle Tuxedo Administration Console on an IBM i 6.1 platform.
Three files $TUXDIR/udataobj/webgui/webguitop.html
, $TUXDIR/udataobj/ tuxwsvr.ini
,and $TUXDIR/udataobj/webgui.ini
need to be modified. For example:
TUXDIRVALUE
" in file $TUXDIR/udataobj/webgui/webguitop.htm
l with the value of TUXDIR
.http://HOST/cgi-bin/tuxadm
" in file $TUXDIR/udataobj/webgui/webguitop.html with "/cgi-bin/tuxadm
".<TUXDIR>
" in file $TUXDIR/udataobj/ tuxwsvr.ini
with the value of TUXDIR
.<TUXDIR>
" in file $TUXDIR/udataobj/webgui/webgui.ini
with the value of TUXDIR
.<LOCAL_HOST>
" in $TUXDIR/udataobj/webgui/webgui.ini
with the host name.
Two programs, tuxwsvr
and wlisten
, need to be run in the background. This can be accomplished by using sbmjob
like tlisten
. For example:
addlible tuxlib
addenvvar envvar('TUXDIR') value('/QOpenSys/tuxedo')
SBMJOB CMD(CALL PGM(tuxwsvr) PARM('-l' '//hostname:8899' '-i' 'TUXDIR/udataobj/tuxwsvr.ini')) JOB(tuxwsvr) CPYENVVAR(*YES)
Current implementation also requires that for all user CGI programs, the HFS library in which they reside be added to the library list.
The procedure for setting up a batch job with wlisten
is similar to setting up a batch job for tuxwsvr
or tlisten
.
To start the Administration Console for Oracle Tuxedo administration on the IBM i 6.1, enter the following URL.
http://machine_name:port/webguitop.html (where machine_name:port
is the IBM i 6.1 machine/port combination on which tuxwsvr
is running).
For additional information on preparing to use the Oracle Tuxedo Administration Console, refer to Starting the Oracle Tuxedo Administration Console in the Oracle Tuxedo Installation Guide.
The combination of the Jolt Relay (JRLY) and its associated Jolt Relay Adapter (JRAD) is typically referred to as the Internet Relay. Jolt Relay routes messages from a Jolt client to a JSL or JSH. This eliminates the need for the JSH and Oracle Tuxedo to run on the same machine as the Web server (which is generally considered insecure).
The program JRLY need to be run background. This can be accomplished by using sbmjob
or sbmdbjob
like tlisten
or tuxwsvr
.
For additional information on Jolt Relay refer to Oracle Jolt.
By default, the tidl compiler does not run the C preprocessor. This means that if you have #define statements or any other pre-processor constructs in the input file, then you will need to specify the -cpp_cmd
option:
call tidl ('-cpp_cmd' 'crtcmod' . . . )
By default, the tidl
command also produces server and client stub files in the current IFS directory. The stub files are named x_cstub.c
and x_sstub.c
. It is also possible to generate stub files in HFS by using the -out option to specify a library in the directory /qsys.lib
, as in the following example:
call tidl ('-out' '/qsys.lib/tuxedo.lib' . . . )
In this case, the stub files will be generated in the physical file idl with members named x_cs
and x_ss
for client and server stubs, respectively. The tidl
command also generates a header file in the current working directory of IFS. For example, if the idl compiler is run on input file x.idl
as follows:
call tidl ('-cpp_cmd' 'crtcmod' '-keep' 'c_source' 'x.idl')
then tidl will generate the following three files in the current working directory of IFS:
In addition, the tidl compiler will copy the header file to member x
belonging to file h
in the qtemp
library.
If the -keep
option is not specified, then the C compiler will be invoked on the stub files to produce object modules x_cs
and x_ss
in library qtemp
. (qtemp
is the default output library which can be overridden by the -out
option, as described earlier.)
The Oracle Tuxedo system supports clients and servers written in the ILE COBOL language. The major differences between MicroFocus COBOL and ILE COBOL are listed below.
The command-line interface for ILE COBOL must use the linkage section rather than the ACCEPT statement.
The method of redirecting output to a file is different. Consult the COBOL Programmer's Guide and COBOL reference manuals for details. Two applications shipped with the Oracle Tuxedo system (CSIMPAPP and STOCKAPP) also show how some tasks are performed on an IBM i 6.1 platform.
You can override the Oracle Tuxedo TMDISPATCH9()
to TMDISPATCH16()
for COBOL routines only when set environment variable TM_COB_STATIC
to YES
before create COBOL program.