|
|
The Oracle Tuxedo Application Runtime for IMS Reference Guide describes system processes and commands delivered with the Oracle Tuxedo Application Runtime for IMS software.
This chapter contains the following topics:
MFSGEN - Binary control blocks generator for server ARTICTL.
This utility is meant for the development of ART MFS. It converts user-written control statements to MFS binary control blocks.
Figure 1shows the MFSGEN workflow.
mfsgen [-options…] files
-l
-d dir
*.MSG and *.FMT)and listing files.
It is <current directory>/format by default.
The MFSGEN utility creates the following files:
FILE.MSG
FILE.FMT
FILE.lst
0
1
2
To convert the source file file.mfs, use the following command:
$mfsgen file1.mfs file.mfs file3.mfs
| Note: | the input file .mfs suffix is not mandatory. |
chgcobol.sh - shell script used to switch between MicroFocus and COBOL-IT for ARTIMS.
chgcobol.sh must be run under the root of IMS_RTchgcobol.sh [mf|cit]
You can have both MicroFocus and COBOL-IT installed at the same host, and may have requirement for switching from one to the other or back. chgcobol.sh is used to switch between MicroFocus and COBOL-IT. To switch COBOL runtime, ARTIMS application must be firstly shutdown.
chgcobol.sh takes the following options:
./chgcobol.shOutput: Current COBOL Runtime is COBOL-IT
./chgcobol.sh mf
Output: COBOL runtime has been changed to MicroFocus
DFSRRC00 - Utility used to activate the ARTIBMP server
DFSRRC00 is used to activate the ARTIBMP server which is always waiting for the input from DFSRRC00. The parameter of DFSRRC00 is a string, which should be passed from the script converted by workbench from JCL. Currently, only the first 3 sub-parameters contained in the string is supported, i.e. “BMP, $(PROG), $(PSB),…”, in which “BMP” is a hard-coded string, $(PROG) represents the batch program to be called, $(PSB) represents the PSB name to be used for the program, the remaining sub-parameters in the string are simply ignored.
DFSRRC00 “BMP, $(PROG), $(PSB),……”
In ARTIMS, DL/I is implemented in a group of dynamically loaded libraries. The supported DL/I functionalities are as follows:
DL/I is responsible for processing incoming messages and building outgoing messages against PCBs in IMS/TM. In ARTIMS, Tuxedo infrastructure is responsible for the message queue and message delivery, so the processing of incoming messages only involves the current request message. DLI library can retrieve the first and subsequent segments (FML fields) based on the request from any COBOL application. For building outgoing message, each PCB has an associated message buffer (FML) as the intermediate storage area, which holds the message data before the message is sent out. Detailed APIs for message processing are listed below.
CBLTDLI - The 0 entry for DL/I calls in IMS/TM on OS/39.
In ARTIMS, CBLTDLI is a function acting as the entry of DLI library. CBLTDLI calls appropriate function based on the function code passed to it.
Function Code, e.g. “GU ”; I/O PCB or alternate PCB, I/O area, MOD
GU - Used to retrieve the first segment from the message queue in IMS/TM environment.
‘AB’: segment I/O area not specified
‘AD’: functional parameter invalid: function call not provided to CBLTDLI or invalid function call name provided to CBLTDLI
‘QF’: segment less than 5 characters
GN - Used to retrieve the subsequent segment from message queue in IMS/TM environment.
After the last segment has been retrieved, a GN call results in a “QD” status code returned in PCB. In ARTIMS, the simulated GN call is used to get next field in the FML buffer of the message being processed.
‘AB’: segment I/O area not specified
‘AD’: functional parameter invalid: function call not provided to CBLTDLI, invalid function call name provided to CBLTDLI
ISRT - Used to add a segment into the message associated with the specified PCB in IMS/TM.
In ARTIMS, the simulated ISRT call is used to add a field of CARRAY type into the FML buffer associated with the specified PCB. For conversational transaction, the first segment is always SPA.
I/O PCB or alternate PCB, I/O Area, MOD
‘AB’: segment I/O area not specified
‘AD’: functional parameter invalid: function call not provided to CBLTDLI, invalid function call name provided to CBLTDLI
‘QF’: segment less than 5 characters
‘QH’: No destination name in PCB
‘XA’: trying to forward the request to another transaction after responding the request
‘XB’: trying to respond the request after forwarding it to another transaction
‘XC’: Z1 bit is not 0, it is reserved and always kept as 0
PURG - Used to tell IMS/TM that the message is complete for non-express PCB.
PURG call is normally, but not send; or send out the message immediately for an express PCB.
If an I/O area is provided to PURG call, PURG call also acts as an ISRT call. That is, PURG marks the (current) message associated with the PCB as complete and “ISRT” the data in the I/O area as the first segment of the next message. The final result is same as a PURG call without I/O area followed by an ISRT call.
In ARTIMS, the simulated PURG call is used to mark the associated message as complete for a non-express PCB, or send out the associated message for an express PCB. If an I/O buffer is provided, however, it is ignored since multiple pending messages for a single PCB are not supported, therefore the MOD is ignored too. No special status code is added for this case, however, since the status code is checked by customer program.
I/O PCB or alternate PCB, I/O Area (optional), MOD (optional)
is a pointer to the PCB that represents the destination of the outgoing message
if provided, is a pointer to a buffer that is to be inserted as the first segment of next message
is the MOD to be used for the output message, the 8-byte MOD name must be left-justified and padded with blanks as necessary.
‘AD’: functional parameter invalid: function call not provided to CBLTDLI, invalid function call name provided to CBLTDLI
‘A3’: a modifiable TP PCB with no destination set but PURG called to it
CHNG -Used to change the destination in PCB in IMS/TM.
In ARTIMS, the simulated CHNG is to specify another service name (only) in an alternate PCB. The destination transaction name is not greater than 8 bytes and is truncated to 8 if the limit is exceeded. The tailing blanks are removed too. The transaction name is evaluated as valid if it exists in the imstrans.desc file and has a legal configuration.
If one transaction code in one Tuxedo domain is designed to switch to another service in a different domain, the transaction code to be switched must be defined in the [imstrans.desc] configuration file as a valid transaction but should NOT be advertised with the control of its class.
For program switch, the new target is another transaction code. For conversational program switch, ARTIMS does not have limitation on the spa sizes of the originating code and the target code.
Alternate PCB, destination transaction code
is a pointer to the PCB that represents the destination of the outgoing message destination name is a string that represents the name of another transaction(service)
‘AD’: functional parameter invalid: destination not provided, functional call invalid
‘A2’: PCB is not modifiable or ISRT operation already done
‘QH’: the transaction to be specified in an alternate PCB is blank or invalid
DLI library performs the database operations issued from MPP or BMP programs. It can retrieves and hold one specific segment according the specified segment search criteria, update a specific segment, insert a segment at a specific position, delete a specific segment, and so on. Detailed APIs for database operation are listed below.
GU/GHU - Retrieve (and Hold) the first segment that satisfies the criteria (if any) from the current position (if any) or the beginning of the database.
GU is used to retrieve the first segment that satisfies the specified SSA and establishes a starting point for sequential processing. The search start point of GU is the beginning of the database, i.e. the root level. After locating the first segment that satisfies the call, current position is the starting position for sequential processing.
GHU locks the segment for sequential write operation, e.g. replace, delete, etc, in addition to GU.
DB PCB, I/O Area, and SSA list (optional)
GN/GHN - Retrieve (and Hold) the next segment that satisfies the criteria (if any) from current position.
GN is used to retrieve the next segment that satisfies the specified SSA, searching from current position. After locating the segment, the current position is updated for sequential processing. If no current position established in the DB, GN acts like GU, i.e. searching from the beginning. Sequential retrieval in hierarchy DB is always from top to bottom and from left to right, i.e. pre-order retrieval in a tree.
GHN locks the returned segment for sequential write operation on it, in addition to GN.
Parameters: DB PCB, I/O Area, and SSA list (optional)
The usage and restriction on parameters of GN are similar to that of GU.
GNP/GHNP - Retrieve (and Hold) the next segment that satisfies the criteria from the dependent segments of the established parent.
GNP is used to retrieve the next qualified segment in the dependent segments of the established parent. The established parent in a hierarchy DB is the lowest-level segment returned in previous successful GU/GN call, and is canceled by an unsuccessful GU/GN call.
GHNP locks the returned segment for sequential write operation in addition to GNP.
DB PCB, I/O Area, SSA list (optional)
ISRT - Used to insert a new occurrence of an existing segment type into a hierarchy database.
ISRT is used to insert a new occurrence of an existing segment type into a hierarchy database. The insert location is determined by a series of qualified SSA excluding the level of the segment being inserted, or by current position if no qualified SSA.
DB PCB, I/O Area, and SSA list
REPL - Used to update an existing segment.
REPL call is used to update an existing segment. Firstly use a Get Hold call to retrieve the segment, then modify the segment and update the segment. The field length of the segment in the I/O area can’t be changed.
DB PCB, I/O Area, and SSA list (optional)
DLET - Used to remove a segment and its dependents.
DLET call is used to remove a segment and its dependents. It must follow a Get Hold call. Qualified SSA must NOT be specified for DLET call.
DB PCB, I/O Area, and SSA list (optional)
FLD - Used to access a field within a segment.
FLD call is used to access a field within a segment. More info here?
DB PCB, I/O Area, and SSA list (optional)
To support different kinds of implementation of IMS/DB, the support for IMS/DB is designed as a dynamically linked library (DLL) that can be plugged into ARTIMS and can be loaded by ARTIMS servers after being plugged. To enable this plug-and-play mechanism, there should be an agreement of what APIs exported by the DLL.
ARTIMS servers (ARTIMPP and ARTIBMP) are used as a container to run an online or batch COBOL program. To enable database access operations issued by the programs, normally the servers need to do some initialization or configuration for database implementation, need to do something prior to invoking a COBOL program, need to do something after completing the program, and need to do some cleanup before the servers go down. Besides, each database operation through "CBLTDLI" need to be mapped to a specific API.
A pointer to DB PCB structure is passed from ARTIMS servers to COBOL programs, and finally to db_entry() of plug-in for IMS/DB. To enable the plug-in work properly, the DB PCB structure should be filled in correctly before calling COBOL program each. This section defines the detailed requirement regarding how to fill in DB PCB.
The DB PCB structure example is shown in Listing 1.
struct {
char dbname[8];
char seglevel[2];
char stat_code[2];
char opt[4];
char res[4];
char segname[8];
char keylen[4];
char segnum[4];
char keyfa[IMS_FEEDAREA_LEN];
};PROCSEQ=<name>, populate dbname with <name>. Otherwise, populate dbname with the name in NAME=<name> from PSB.PROCOPT option from the PCB statement in PSBYou must do the following steps to define an API for IMS/DB plug-in:
extern "C" int db_init(int argc, char * argv[])
Functionality: Initialization for configuration or others required by an implementation
Arguments: parameter list passed from CLOPT of the servers
Return Value: 0 - success, -1 -- failure
Where to use: This API is called while an ARTIMS server starts. If a specific implementation of IMS/DB doesn't need any initialization work, just provide an empty function and make it return 0.
Functionality: Cleanup for configuration or others required by an implementation
Arguments: None, because the servers can't provide input for Plug-in
Return Value: 0 - success, -1 -- failure
Where to use: This API is called while an ARTIMS server shuts down. If a specific implementation of IMS/DB doesn't need any initialization work, just provide an empty function and make it return 0.
Functionality: Pre-Action required by an implementation before invoking a COBOL program which may access IMS/DB implementation
Arguments: None, because the servers can't provide input for Plug-in
Return Value: 0 - success, -1 -- failure
Where to use: This API is called before ARTIMS servers invokes a COBOL program that may access IMS/DB implementation. If a specific implementation of IMS/DB doesn't need any initialization work, just provide an empty function and make it return 0.
Functionality: Post-Action required by an implementation after invoking a COBOL program which may access IMS/DB implementation
Arguments: None, because the servers can't provide input for Plug-in
Return Value: 0 - success, -1 -- failure
Where to use: This API is called after ARTIMS servers invokes a COBOL program that may access IMS/DB implementation. If a specific implementation of IMS/DB doesn't need any initialization work, just provide an empty function and make it return 0.
int dbentry(const char * op, __DB_PCB * pcb, void * io, char * ssa_list[], int ssa_cnt);
Functionality: The entry point of accessing the IMS/DB implementation. Each DL/I call for database access issued from a COBOL program is finally handled by it.
op: function call name, e.g. "GU "
pcb: pointer to a __DB PCB, which is a superclass of user provided DB PCB.
io: pointer to a buffer, DB_IO_AREA is defined by the external implementer
ssa_list: an array of strings, each containing a SSA, the format is up to the external implementer
ssa_cnt: number of elements in ssa_list, the value range is [0..15]
Within ARTIMS, a default DLL is provided as the placeholder of database plug-in. The default DLL contains only the implementation of GSAM database.
DLI library performs the transaction management work, i.e .committing the changes that have been made and sending out the messages already built or rolling back all the changes and drop out all the messages, according to the direction passed from COBOL application. If the COBOL application does not issue a clear direction to commit the transaction, ARTIMPP commits the transaction.
CHKP - Used to set an explicit commit point.
CHKP call is used to set an explicit commit point. At a commit point, IMS/TM commits the changes made by application programs, normally database updates, sends out all the message marked as complete (by PURG for non-express PCB), and retrieves the next input message into the IOAREA provided.
In ARTIMS, the simulated CHKP is used to commit the changes already made by using tpcommit(). The messages that have been marked by complete are sent out. The messages that have not been marked by explicit PURG call are sent out too. Since there is only one message being processed, so no next message is retrieved.
‘ bb’: successful (two blanks)
‘AD’: functional parameter invalid: function call not provided to CBLTDLI, invalid function call name provided to CBLTDLI
ROLB - Used to cancel the database updates.
ROLB call is used to cancel the database updates, cancels all the messages that were inserted but not available for transmission. For express PCB, the message is made available for transmission when IMS knows that the message is complete, i.e. when a PURG call is called. For non-express PCB, the message is not made available for transmission until the program reaches a commit point.
In ARTIMS, the simulated ROLB call is used to roll back all the changes made by the application program by using tpabort(), and empty the message buffers that have not been sent out.
‘ bb’: successful (two blanks)
‘AD’: functional parameter invalid: function call not provided to CBLTDLI, invalid function call name provided to CBLTDLI, or PCB not provided
ARTICL -Used to join 3270 terminal to ART IMS Runtime.
You must specify the MAXWSCLIENTS parameter in the MACHINES section of the UBBCONFIG file. MAXWSCLIENTS is the only parameter that has special significance for ARTICTL. MAXWSCLIENTS tells the Oracle ART at boot time how many accesser slots to reserve exclusively for 3270 terminals.
For MAXWSCLIENTS, specify the maximum number of 3270 terminal that may connect to a node. The default is 0. If not specified, terminal may not connect to the machine being described.
The syntax is MAXWSCLIENTS=number.
CLOPT="[servopts options] -- -n netaddr -L pnetaddr [-m minh] [-M maxh] [-x session-per-handler] [-D] [+H trace-level]"
minh and maxh based on system load.
| Note: | Although minh is a number from 1 to 255, but it still should be equal to or smaller than (FD_SETSIZE - 24) according to the system resources limits. FD_SETSIZE means the maximum number of files that a process can have open at any time. The value can be acquired via system command ulimit -n. |
ARTICTL, maxh is a number from 1 to the 1000; the default value is 1000. The actual number of handler processes is always between minh and maxh based on system load.
| Note: | Although maxh is a number from 1 to 1000, it should be equal to or smaller than (FD_SETSIZE - 24) according to the system resources limits. FD_SETSIZE means the maximum number of files that a process can have open at any time. The value can be acquired via system command ulimit -n. |
*MACHINES
DEFAULT:
MAXWSCLINETS = 20
...
*SERVERS
ARTICTL SRVGRP="MFSGRP"
SRVID=1000
RESTART=Y GRACE=0
CLOPT="-- -n //hostname:4000 -L //hostname:4002 -m 1 -M 10"
ARTIMPP -Service handler and container for TP type COBOL programs.
ARTIMPP is a Tuxedo server to act as both service handler and container for COBOL programs of TP type, it invokes corresponding COBOL program according to the service request received.
CLOPT="[servopts options] -- – l class_list -D -x parameter list for DB plugin"
class_list are advertised by ARTIMPP.
db_init().
ARTIMPP_ORA has all the functionalities of ARTIMPP. It can also support an Oracle database used as an external resource manager (RM). It uses on some libraries provided by Oracle database. In order to use this environment variable it with an Oracle database, the RM section must be configured correctly in the UBBCONFIG file.
ARTIBMP - Program container for BATCH type COBOL programs.
ARTIBMP is a Tuxedo server to act as the program container for COBOL programs of BATCH type, it invokes corresponding COBOL program according to the program name received.
CLOPT="[servopts options] -- -D-x parameter list for DB plugin"
db_init().
ARTIBMP_ORA has all the functionalities of ARTIBMP. It can also support an Oracle database used as an external resource manager (RM). It uses on some libraries provided by Oracle database. In order to use this environment variable it with an Oracle database, the RM section must be configured correctly in the UBBCONFIG file.
ARTIADM - A tuxedo server responsible for the administration of ART IMS Runtime.
In a distributed target environment, this server can be configured on each node to achieve the configuration propagation. With these servers, the configuration files only need to be configured on the master node, and the administration servers propagate the configuration files to each slave node.
When starting up, the administration server running on the master node reads in all the configuration files located in directory ${ART_IMS_CONFIG}. When each administration server running on a slave node starts up, it communicates with the administration server on the master node and fetches the contents of the configuration files.
The administration server on the slave node then writes to the corresponding configuration files in directory ${ART_IMS_CONFIG} on the slave node. New configuration files are created if none exist.
ARTITERM - Acts as messenger between ARTICTL and ARTIMPP located in different domains.
In cross-domain environment, ARTITERM server is used to act as messenger between ARTICTL and ARTIMPP located in different domains. ARTITERM provides a special service for ARTIMPP so that ARTIMPP can pass data to ARTITERM, which in turn passes the data to ARTICTL.
The definition of message formats and device formats is accomplished with separate hierarchic sets of definition statements. Table 5 shows all the definition statements and their descriptions.
The “END” statement in above table defines the end of input file. All contents after it will be ignored. If the input file doesn’t have an “END”, MFSGEN will give an warning message and add one for the input file.
For each statement name, there are several fields. The detailed field name and value requirements are listed in Table 2 and Table 3. All other statements are assumed unsupported fields currently (listed in table 4). Sample 1 in Appendix A shows an example control statements file.
| Note: | system-literals include: TIME, DATE1, DATE2, DATE3, DATE4, DATE1Y4, DATE2Y4, DATE3Y4, DATE4Y4, YYDDD, MMDDYY, DDMMYY, YYMMDD, YYYYDDD, MMDDYYYY, DDMMYYYY, YYYYMMDD, DATEJUL, DATEUSA, DATEEUR, DATEISO, LTSEQ, LTNAME. |
| Note: | For LTMSG and LPAGENO, user will get a warning message and they will not take any effect. For other strings not in above list, user will get a syntax error. |
For the last column in above tables, “Support” means the field is supported; “Warning” means the field is not supported, and the tool ignores this field just like it is not specified, meanwhile a warning is generated; “Error” means the field is not supported, the tool reports an error and fails parsing current definition statement set.
In Tuxedo, each type of security mechanism requires that every user provide an application password as part of the process of joining the Tuxedo ATMI application, but In ART IMS, it has been removed in order to keep the same behavior as IMS resides on z/OS. User should keep application password as NULL. For more information on how to configure Tuxedo application
password, please refer to Tuxedo documentation. The USER_AUTH and ACL/Mandatory ACL security mechanism requires that each user must provide a valid username and password to join the ART IMS runtime. The per-user password must match the password associated with the user name stored in a file named tpusr. Client name is not used. The checking of per-user password against the password and user name in tpusr is carried out by the Tuxedo authentication service AUTHSVC, which is provided by the Tuxedo authentication server AUTHSVR. For more information on how to configure Tuxedo USER_AUTH and ACL/Mandatory ACL authentication, please refer to Tuxedo documentation.
ART_IMS_DB
is the container path where GSAM files are located.ART_IMS_CONFIG
An environment variable required by ART IMS to specify the absolute path where the configuration files are located, such as *.desc and *.psb.ART_IMS_FMT
An environment variable required by ARTICTL to specify the absolute path where the control block files which generated via MFSGEN are located. It is a series of paths similar to PATH environment variable, the separator is : .If this variable is not specified, the PATH APPDIR will be used.COBPATH
An environment variable required by Microfocus COBOL environment. It defines one or more directories to search COBOL programs to be loaded dynamically. Its usage is similar to Unix PATH.COB_LIBRARY_PATH
If you are using COBOL-IT, COB_LIBRARY_PATH is required by COBOL-IT to define the search order for COBOL programs. It defines one or more directories to search COBOL programs to be loaded dynamically. Its usage is similar to Unix PATH.
Following table lists the commands and associated parameters that can be input on 3270 terminal and be processed by ARTIMS.
| Table 13 Command | Table 14 Shortening | Table 15 Parameter |
|---|---|---|
All the configuration files in this section are case insensitive for key and non-literal values, for example bool (yes|no) and enum. Literal values and their cases are kept. Comment line should be prefixed with “*”.
The configuration files are as follows:
The general format for configuration files is as follows.
[section name]
Field1=value1
Field2=value2
….
[section name]
….
[section name]
…
The fields in this configuration file are mapped from TRANSACT MACRO of IMS on z/OS
The fields in this configuration file are mapped from APPLCTN MACRO of IMS on z/OS.
imsdbs.desc is located under $ART_IMS_CONFIG.
Some fields of imsdbs.desc configurations are mapped from some DBD statement of IMS on z/OS.
$appname is the name of a COBOL application program with type of TP defined in imsapps.desc, $appname.psb is the PSB definition file corresponding to it. For application program with type of BATCH, $appname.psb is not used and the PSB must be provided by the script that calls DFSRRC00.
The fields in this configuration file are mapped from PCB statement for IMS on z/OS.
|