Table 1 lists the Tuxedo ART for IMS utilities.
chgcobol.sh - shell script used to switch between Micro Focus COBOL and COBOL-IT for Tuxedo ART for IMS.
DFSRRC00 - Utility used to activate the
ARTIBMP or
ARTIBMPT server.
DFSRRC00 "BMP,${MBR},${PSB},${IN},,,,,${CKPTID},,,,,,,,,,,,"
DFSRRC00 is used to activate the
ARTIBMP/ARTIBMPT server which waits for
DFSRRC00 input . The
DFSRRC00 parameter is a string passed from the script converted by workbench from JCL. Currently, only 5 sub-parameters contained in the string are supported :
“BMP, ${MBR}, ${PSB}, ${IN}, ${CKPTID}” . The remaining sub-parameters in the string are ignored.
The DFSRRC00 client name format is as follows:
“${MBR}-DFSRRC00”. You can use
tmadmin to observe currently running BATCH programs.
Two duplicated FML32 fields (IMS_BMP_APPNAME_ROUTE and
IMS_JOB_NAME_ROUTE) could be used as routing fields when
DFSRRC00 calls the BMP service. So you could route a specific application program or Batch job to a specific BMP server group. These two FML32 fields are defined in
$IMSDIR/include/ROUTEFML.
Notes:
|
When ${MBR} is empty, DFSRRC00 exits with error directly.
|
When ${IN} is empty, the request is sent to
ARTIBMP/
ARTIBMP_ORA to call a
BMP program.
When ${IN} is not empty, the request is sent to
ARTIBMPT to call transaction oriented BMP program whose transaction code is
${IN}.
imsadmin - Tuxedo ART for IMS Runtime administration tool.
imsadmin supports the following options:
Note:
|
When security level is set to MANDANTORY_ACL, to ensure imsadmin successfully transmits reloading request to Tuxedo ART for IMS servers, you must make sure the username in the profile has access permission to the services named “ ..IMSADM _grpid_svrid”, where the grpid/svrid represents every Tuxedo ART for IMS MPP/BMP corresponding group id and server id.
|
flushperf: Flushes the performance trace into log files.
cleanperf: Cleans up the performance trace log files.
1: Function stack trace + execution flow trace
2: Function stack trace + execution flow trace + data convert trace
If machine,
groupid, and
serverid parameter are not specified, the action is applied to all applicable servers specified in the
UBBCONFIG SERVERS section. Once you specify one or more parameters, the action is only applied to the servers specified.
Notes:
|
If flushperf or cleanperf are specified, -m, -g and -s are be omitted, since these two actions apply to all applicable servers.
|
•
|
Reload COBOL programs PGM1 and PGM2 in all Tuxedo ART for IMS application servers, input the following: imsadmin -l PGM1,PGM2.
|
imsgenconf - Tuxedo ART for IMS configuration generation tool.
imsgenconf allows you to generate Tuxedo ART for IMS configurations for particular transactions and batch applications.
During the file generating process, imsgenconf validates field definitions that Tuxedo ART for IMS uses according to the fields defintion. If the validation fails, the specific error is reported and the configuration file generation stops.
If successful, a report file (imsgenconf_report)is generated in the output directory. Currently, transactions with definition file name and line number are included in the report file.
-i inputdir is obsoleted by Tuxedo ART for IMS 12c Release 2 (12.1.3) Rolling Patch 042 and later.
imsperf - Tuxedo ART for IMS Runtime Performance analysis tool
If -d option is specified, it searches the performance trace file under the specified path.
If -d option is not specified, it searches performance trace first under
$IMS_TRACE_PATH, then under
$APPDIR/log. For more information, see
Tuxedo ART for IMS Users Guide.
imsperf generates transaction/application performance reports in the same directory as the performance trace file; the formats are as follows:
imsperf supports the following options:
MFSGEN - Binary control blocks generator for
ARTICTL. server.
It is <current directory>/format by default.
The MFSGEN utility creates the following files:
odbactl - Open system tool used to stop ODBA proxy on z/OS, check status of ODBA proxy on z/OS, show existing connections, and check if PSB is properly defined.
Use odbactl on open systems which provides varies functions.
odbastop - Open system tool used to stop ODBA proxy on z/OS.
Use odbastop on open systems to stop ODBA proxy running on z/OS.
prepro-ims.pl - Utility used to transfer C program on z/OS to the format that could be run in Tuxedo ART for IMS.
prepro-ims.pl is used to transfer C programs on z/OS to a format that can be run in Tuxedo ART for IMS. When file conversion failes, the failure information and lines of source file leading to failure are printed to the
stderr.When complete, a summary is reported to
stdout.
The env(IMS) establishes the correct operating environment and
plist(IMS) establishes the correct parameter list when invoked under IBM IMS. They are not necessary in Tuxedo ART for IMS Runtime and should be removed.
Functions ctdli()/
aibtdli() are reconstructed by adding additional trailing
NULL to the argument list. This
NULL is used to mark the end of the Tuxedo ART for IMS argument list. For
aibtdli(), the
parmcount parameter is removed.
The function main()argument list is eliminated (including "
argc", "
argv" and "
envp"). On mainframes, IMS uses a global list and a macro to define the list. On Tuxedo ART for IMS, the
__getcb(int) function is implemented as
GET method to obtain the PCB list.
The exit() function is renamed to
__art_ims_return (). According to IBM IMS documentation, when there are no messages for the program to process, the program returns control to IMS by returning from main or by calling
exit(). To avoid
exit() unexpectedly exiting the container server, The
__art_ims_return () function is used and helps to return control to container server.
Table 2 shows processing rules examples.
Note:
|
prepro-ims.pl cannot handle all generic C porting from mainframes to open systems.
|
2.
|
Invoking ctdli/aibtdli as a function pointer is not supported.
|
1.
|
gmake should be used for the generated makefile.
|
/* #pragma runopts(env(IMS), plist(IMS)) */
#include <ims.h>
#include <stdio.h>
#define n 20 /* I/O area size - Application dependent */
typedef struct {PCB_STRUCT(10)} PCB_10_TYPE;
int main()
{
static const char func_GU[4] = "GU ";
static const char func_ISRT[4] = "ISRT";
char ssa_name[] = "ORDER ORDER (ORDERKEY = 666666)";
int rc;
char msg_seg_io_area[n];
char db_seg_io_area[n];
char alt_msg_seg_out[n];
PCB_STRUCT_8_TYPE *alt_pcb;
PCB_10_TYPE *db_pcb;
IO_PCB_TYPE *io_pcb;
io_pcb = (IO_PCB_TYPE *)__pcblist[0];
alt_pcb = __pcblist[1];
db_pcb = (PCB_10_TYPE *)__pcblist[2];
..
/* get first message segment from message area */
rc = ctdli(func_GU, io_pcb, msg_seg_io_area, NULL);
..
/* get the data from the database having the specified key value */
rc = ctdli(func_GU, db_pcb, db_seg_io_area, ssa_name, NULL);
..
/* build output message in program's I/O area */
rc = ctdli(func_ISRT, alt_pcb, alt_msg_seg_out, NULL);
..
}
RUNPROXY - Used to start ODBA proxy on z/OS.
Use RUNPROXY on z/OS to start ODBA proxy on z/OS.
STOPROXY - Used to stop ODBA proxy on z/OS.
Use STOPROXY on z/OS to stop ODBA proxy running on z/OS.
Table 6 lists supported DL/I interfaces.
|
|
|
|
|
AIBTDLI is an entry function for the whole DL/I layer. The essential difference from CBLTDLI is that AIBTDLI uses AIB mask as the first parameter to pass control information in and out.
|
|
CTDLI is an entry function for the whole DLI library. Any request to DLI is passed by calling this function. CTDLI can only be called from C programs.
|
CBLTDLI - The 0 entry for DL/I calls in IMS/TM on OS/39.
In Tuxedo ART for IMS, CBLTDLI is a function acting as the entry of DLI library.
CBLTDLI calls appropriate function based on the function code passed to it.
AIBTDLI - an entry function for the whole DL/I layer.
AIBTDLI is an entry for DL/I calls in IMS/TM on z/OS. In Tuxedo ART for IMS,
AIBTDLI is a function acting as an entry of the DL/I library.
AIBTDLI gets the PCB address according to the PCB name specified in AIB mask, then calls appropriate function based on the function code passed to it with the PCB address found.
The name of alternate PCB must be configured with "label=" in
$appname.psb configuration file, and must be specified correctly in AIB mask, the name (label) of each alternate PCB must be unique in a single PSB (i.e., in a single
$appname.psb file).
The name of DB PCB must be configured with "label=" in
$appname.psb configuration file, and must be specified correctly in AIB mask, the name (label) of each DB PCB must be unique in a single PSB (i.e., in a single
$appname.psb file).
CTDLI - An entry function for the whole DL/I layer.
In Tuxedo ART for IMS, CTDLI is a function acting as the entry of DLI library.
CTDLI calls appropriate function based on the function code passed to it.
The op argument specifies the DL/I function to be performed. The
ctdli() call format depends on the function selected. For more information, see
CBLTDLI.
GU - Used to retrieve the first segment from the message queue in IMS/TM environment.
GU is used to retrieve the first segment in a message. For conversational transaction, the first segment of a message is always SPA.
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 Tuxedo ART for IMS, the simulated
GN call is used to get next field in the FML buffer of the message being processed.
ISRT - Used to add a segment into the message associated with the specified PCB in IMS/TM.
‘bb’: successful (two blanks)
‘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.
'A6': Output segment size limit exceeded on call.
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 Tuxedo ART for IMS, 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.
‘bb’: successful (two blanks)
‘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 Tuxedo ART for IMS, 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.
‘bb’: successful (two blanks).
‘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.
CMD - Used to enable a program to issue IMS commands.
CMD is used to issue IMS commands. It forwards the IMS command to an interface which can assumedly process all supported IMS commands. The CMD call waits for the interface to process IMS commands, and get the first field of the response message.
For commands, only "/DIS TRAN", "
/DIS PGM" and "
/DIS USER" are supported. Once these commands are issued by CMD API, related title segment will be returned through the I/O area, which describes the meaning of each field in subsequent segments.
If "tranname" represents a persistent transaction, only
TRAN,
CLS, and
QCT are supported and will have value in returned segment for
GCMD. If "tranname" represents a non persistent transaction, only
TRAN,
CLS are supported and will have value in returned segment for
GCMD.
For "/DISP TRAN tranname QCNT", returned segment is (excluding the llzz part):
T70 TRAN GBLQCT. Only
TRAN is supported,
GBLQCT will be always N/A in returned segment for
GCMD.
TRAN: The name of the transaction, 8 bytes.
CLS: The class of the transaction, 3 bytes.
ENQCT: Not supported, 5 bytes
QCT: The left message count(queue count ) in queue of the transaction, 5 bytes.
- The tranname is only handled by the current Tuxedo ART for IMS server.
-The DISPLAY TRAN is issued after a
CHKP without an
IOAREA.
GCMD - Retrieves the second and subsequent segments of the response message of a CMD command.
GCMD retrieves the second and subsequent response segments from IMS TM when your application program processes IMS commands using the CMD call. Each returned segment contains the fields according to the title segments of above "CMD" Call. After the last segment has been retrieved, a GCMD call results in a "QD" status code returned in PCB.
GUID - A fake DL/I used to retrieve the full username under
ARTIMPP server long username mode.
GUID is used to retrieve the full
ARTIMPP server username only recommended under long username/password mode.
GU/GHU -
Retrieves (and Holds) the first segment that satisfies the criteria (if any) from the current position (if any) or the beginning of the database.
DB PCB,GSAM PCB or
AIB, I/O Area, and SSA list (optional) or
RSA (Mandantory for GSAM)
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, the 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.
GHU is not applicable for GSAM.
Note:
|
The RSA "00010000" resets the position to the start of the GSAM.
|
GN/GHN -
Retrieves (and Holds 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.
GHN is not applicable for
GSAM.
GNP/GHNP - Retrieves (and Holds) 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.
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.
REPL - Used to update an existing segment.
REPL is used to update an existing segment. you must firts 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 cannot be changed.
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.
FLD call is used to access and change a field within a segment.
POS - A qualified Position (POS) call is used to retrieve the location of a specific sequential dependent segment. An unqualified POS points to the logical end of the sequential dependent segment (SDEP) data.
POS only supports DEDB. In Tuxedo ART for IMS, it has the following limitations:
1. keyword parameters are not supported.
OPEN - Used to explicitly open a GSAM database.
Tuxedo ART for IMS 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.
•
|
dbname: If the PCB statement in PSB contains a PROCSEQ=<name>, populate dbname with <name>. Otherwise, populate dbname with the name in NAME=<name> from PSB.
|
•
|
opt: Populate with value set to PROCOPT option from the PCB statement in PSB
|
•
|
res: Do not populate with anything
|
•
|
keylen: Do not populate with anything
|
•
|
segnum:Do not populate with anything
|
•
|
keyfa: Populate with NULL
|
Listing 3 shows the structure definition used for the
get_dbpcbattr interface. The content is read from th
PSB file and returned to application through
get_dbpcbattr interface.
Functionality: Initialization for configuration or others required by an implementation
Arguments: parameter list passed from CLOPT of the servers
Where to use: This API is called while an Tuxedo ART for IMS 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
Where to use: This API is called while an Tuxedo ART for IMS 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
Where to use: This API is called before Tuxedo ART for IMS 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
Where to use: This API is called after Tuxedo ART for IMS 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.
Return Value: PCB Attribute pointer, the user can't modify anything contained in the PCB attribute structure returned by this API; If the input is not DB PCB or GSAM PCB, null is returned; If any optional attribute is not configured, default value is returned;No need to free the pointer;
Table 10 lists the transaction management processes and commands.
CHKP (Basic) - Used to set an explicit commit point.
CHKP 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 Tuxedo ART for IMS, 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.
CHKP (Symbolic) - Used to set an explicit commit point. Sets a check point from which the program can be started, saves as many as seven data areas in the program, and records current
GSAM DB retrieval position.
CHKP (Symbolic) can be used for recovery purposes. It commits all changes made by the program and, if your application program abends, establishes the point at which the program can be restarted. In addition, the symbolic
CHKP call can:
Note:
|
If ART BMP server was restarted after user used symbolic CHKP to store data area, but before user uses XRST to restart program, the stored data area by symbolic CHKP will not be restored by XRST.
|
CHKP record will be saved in record log file named “programname.psbname.log”. An environment variable
ART_IMSLOGDIR is used to specify the directory where the record log files are located. If environment variable
ART_IMSLOGDIR is not set, its default value is
$APPDIR/IMSLOGDIR.
For MP mode, if you want to share the record log file among machines, the ART_IMSLOGDIR should point to NFS directory which machines in the Tuxedo domain could access. The
CHKP record is always appended to the record log file by Symbolic
CHKP and the saved record will not be deleted at any time except the user empty the record log file manually. Duplicate
CHKP records are be appended to the
CHKP record file.
ROLB - Used to cancel the database updates.
ROLB is used to cancel the database updates. It 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 Tuxedo ART for IMS, 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.
ROLL 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 Tuxedo ART for IMS, the simulated ROLL 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, then it return control to Tuxedo ART for IMS but don't return control to the calling program.
SYNC - Used to commit the changes made by application programs (normally database updates).
INQY-Used to request information regarding execution environment, destination type and status, and session status. INQY is valid only when using the AIBTDLI interface.
For NULL subfunction, ART/IMS can only return the PCB related information that ART/IMS can support into the I/O area. "Terminal Location" and "Transaction Location" are only supported using "LOCAL".
For "FINDbbbb", the PCB address is returned in the AIBRSA1 field.
Subfunction "PROGRAMb" returns the program name in the first 8 bytes of the I/O area.
For "DBQUERYb" subfuntion, if there is no
DBPCB in defined in PSB, "BJ" is returned in the IO PCB status. Otherwise, the IO PCB status is returned according to database availability.
In IMS, after the "DBQUERYb" call, status codes in each DB PCB should not be used to check DB status.
XRST - Used to restart your program. If you use the symbolic Checkpoint call in your program, you must use the XRST call.
XRST is used to restart your program. If you use the symbolic Checkpoint call in your program, you must use the
XRST call.
In Tuxedo ART for IMS, the simulated XRST is used to recover the data that was saved in the related
CHKP (symbolic) call. The
GSAM is repositioned to the recorded position where the
CHKP (symbolic) call occurs so that all subsequent “
GN” calls continue with the recovered position. The status codes of all related
GSAM/DB PCB are blank after the successful
XRST call (with an existing
CHKPID).
For specific CHKP ID:
XRST searches the
CHKP record use the following search key in record log file from the beginning to the end:
Job name + program name + psb name + CHKP ID. If the first
CHKP record matches the search key,
XRST restores the data in this record and returns success. If no
CHKP record matches the search key,
XRST abends.
For CHKP ID ‘LAST’:
XRST searches the
CHKP record using the following search key in record log file from the end to the begining:
Job name + program name + psb name. If the first
CHKP record match the search key,
XRST restores the data in this record and return success. If no
CHKP record matches the search key,
XRST abends.
CEE3ABD requests that Tuxedo ART for IMS terminate the execution of the program with an abend code. There is no return from this function, nor is there any condition associated with it. In Tuxedo ART for IMS you can initiate this function by doing the following:
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.
|
For LTMSG and
LPAGENO, a warning message is displayed and will not take any effect. For other strings not in
Table 12, a syntax error. is displayed
Tuxedo ART for IMS provides a server, ARTIGW, working as a bridge between Non-terminal clients and the Tuxedo ART for IMS MPP server. A non-terminal client calls the
ARTIGW service following the programming interface list below.
ARTIGW forwards the service request to
ARTMPP.
IMS_SEG_DATA
Application buffer data. LLZZ is not expected in the buffer. The maximum segment length is
32764 (which is the
ARTIMPP limit).
Here < tuxclt_service_name> is the ARTIGW advertised service; the service name is configurable. For more information, see ARTIGW CONFIGURATION.
0: ARTIMPP processes the request successfully with a response message.
1: ARTIMPP processes the request successfully without a response message.
IMS_SEG_DATA
Buffer contains reply data. LLZZ is not included in the buffer.
IMS_SVC_SYSMSG
Verbose error message if IMS_SVC_RESULT is a negative integer.
#name rel-number type flags comment
#----- ----------- ------ ------- ------------------------
IMS_SVC_NAME 181 string
IMS_SVC_FLAG 182 long
IMS_SVC_RESULT 183 long
IMS_SEG_DATA 184 carray
IMS_SVC_SYSMSG 185 carray
Here < mq_service_name> is the
ARTIGW advertised service; the service name is configurable. For more information, see
ARTIGW Configuration.
2.
|
In the TM_MQI configuration file * SERVER section, the following parameters must be specified.
|
3.
|
In the UBBCONFIG file, TM_MQI server must be in a Group configured with TMS Server for the WebSphere MQ Resource Manager.
|
ARTIGW is a Tuxedo server working as a bridge between non-terminal client and the
ARTIMPP server. For more information, see
Server Configurations.
If ARTIGW and
ARTIMPP are deployed in different domains,
ARTIGW exports services named as
<tuxclt_service_name>_REPLY_<grpid>_<srvid> and
<mq_service_name>_REPLY_<grpid>_<srvid>. The
GRPID and
SVRID are 5 characters (starting with 0).
For example, assume that ARTIGW is in domain
GW and
ARTIMPP is in domain
MPP.
ARTIGW is configured to use default service name with
SRVID=101, SRVGRP= GROUP1.
Listing 5 shows an example of the
DMCONFIG files for
MPP and
GW domains.
1. No data conversion is done by the ARTIGW for non-terminal tuxedo clients. The data provided by the client application should be in the format expected by ARTMPP server and application programs.
2. ARTIGW is a single thread Tuxedo server. User can deploy multiple instance of
ARTIGW for performance tuning.
Note: On open systems, IMS transaction is triggered immediately.
4. For MQ Applications, if an unexpected event occurs with ARTIGW or
ARTIMPP during message processing, a report message is generated and sent to the reply queue specified by original message. The report message contains no data from the original message, only a string containing the detailed error message
1.
|
Only Commit mode 0 (COMMIT_THEN_SEND) is supported. Tuxedo ART for IMS will always handle the transaction as Commit mode 0 no matter what the Commit mode value is set in MQIIH.
|
ARTIMPP in normal mode will advertise transactions as services and handle the normal service request from front end, such as terminal request, request from
ARTIGW.The service request is scheduled by Tuxedo framework and is passed via Tuxedo IPC queue.
ARTIMPP in persistent mode will not advertise any services. It will monitor every /Q for the persistent transaction whose
CLASS belong meet the"
-l class_list" parameter of the
ARTIMPP. It gets the message from the /Q of the persistent transaction and execute corresponding program for the transaction.
ARTIBMPT is also a server that is related to persistent message support. The transaction oriented
BMP program that
ARTIBMPT serves must only be persistent transaction. For what is "transaction oriented
BMP“, please refer to
ARTIBMPT configuration section. In transaction oriented
BMP program, the GU operation will get message from the /Q of the transaction.
Table 18 Lists the server configuration processes and commands.
|
|
|
|
|
|
|
Same as ARTIMPP. However, it requires the Oracle database as RM
|
|
|
|
Same as ARTIBMP. However, it requires the Oracle database as RM.
|
|
|
|
|
|
Acts as messenger between ARTICTL and ARTIMPP located in different domains.
|
|
|
|
|
|
|
ARTICL - Used to join 3270 terminal to Tuxedo ART for 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 access 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.
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.
|
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.
|
Note:
|
To join Tuxedo domain, ARTICTL only uses APP_PW stored in the security profile, the username/user password the ARTICTL uses comes from 3270 terminal.
|
The -D option is used to enable
ARTICTL server trace log. If not specified, it is disabled. The
+H handler-number option is used to enable
ARTICTLH server trace log only for the first booted number of
ARTICTLH servers enabled handler-numbers. When handler-number is
0, trace log is enabled in all
ARTICTLH servers created from the current
ARTICTL servers. All trace logs are placed in the
/tmp directory.
ARTIMPP - Service handler and container for TP type COBOL/C programs.
ARTIMPP is a Tuxedo server to act as both service handler and container for COBOL/C programs of TP type. There are two running modes for
ARTIMPP, one is
ARTIMPP in normal mode (without
-p in
CLOPT), another is
ARTIMPP in persistent mode (with
-p in
CLOPT).
ARTIMPP in normal mode invokes corresponding COBOL/C program according to the service request received from front end (request from terminal,
ARTIGW).
ARTIMPP in persistent mode will monitor /Q for persistent transaction whose class is defined in the "
-l class_list" parameter in
CLOPT for the
ARTIMPP. It will get the message from the /Q and invoke corresponding COBOL/C program.
ARTIMPP is in persistent mode.
ARTIMPP in persistent mode will not advertise any services/transactions.
0 : function stack info is logged.
1 : debugging trace info is logged.
2 : more detailed data info islogged.
Notes:
|
When ARTIMPP server is configured in persistent mode in the UBBCONFIG file and persistent transaction is configured in imsresource.desc, TMQUEUE server must also be configured (before ARTIMPP), in the UBBCONFIG file according to the /Q configuration in imsresource.desc.
|
For a persistent transaction that may issue ROLB or
ROLL, the transaction could only be handled by one
ARTIMPP in persistent mode server. That is, the
CLASS definition of the transaction (defined in
imstrans.desc) could only match one
ARTIMPP in persistent mode server
-l parameter.
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/C programs.
ARTIBMP is an Oracle Tuxedo server to act as the program container for COBOL/C programs of BATCH type, it invokes corresponding COBOL/C program according to the program name received. If there is no error, no abend, and the user program has not crashed, the user program return code is returned to
DFSRRC00.
0 : function stack info is logged.
1 : debugging trace info is logged.
2 : more detailed data info islogged.
ARTIBMPT - An OracleTuxedo server that handles transaction oriented batch programs.
A transaction oriented BMP program should be served by
ARTIBMPT and triggered via
DFSRRC00 with
${IN} parameter. A transaction oriented
BMP program is a program that is defined in
imstrans.desc and also defined in
imsapps.desc with a
TYPE=BATCH.
The transaction oriented BMP program must be a persistent transaction and must be defined in
imsresource.desc.
ARTIBMPT server only handles transaction oriented BMP programs.
0 : function stack info is logged.
1 : debugging trace info is logged.
2 : more detailed data info islogged.
Note:
|
When ARTIBMPT is configured in UBBCONFIG file and there is transaction oriented BMP transaction which is configured in imsresource.desc, TMQUEUE server must be also configured in UBBCONFIG file according to the /Q'configuration in imsresource.desc.
|
That is, the CLASS definition of the transaction (defined in imstrans.desc) could only match one
ARTIBMPT server "
-l class_list" parameter.
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 - An Oracle Tuxedo server responsible for the administration of Tuxedo ART for IMS Runtime.
0 : function stack info is logged.
1 : debugging trace info is logged.
2 : more detailed data info islogged.
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.
ARTIGW - An Oracle Tuxedo server working as a bridge between non-terminal client and the
ARTIMPP server.
ARTIGW is an Oracle Tuxedo server that acts as a bridge between non-terminal clients and the
ARTIMPP server. Its main duties are as follows:
0 : function stack info is logged.
1 : debugging trace info is logged.
2 : more detailed data info islogged.
Note:
|
Both the mq_service_name and tuxclt_service_name cannot begin with " <domainid>_". Otherwise ARTIGW cannot obtain the correct response message. In this instance, <domainid> is the ID of the domain which ARTIMPP belongs to.
|
IMSCONN - Used to join IMS Connect client to Tuxedo ART for 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
IMSCONN.
MAXWSCLIENTS tells the Oracle ART at boot time how many access slots to reserve exclusively for IMS Connect clients.
For MAXWSCLIENTS, specify the maximum number of IMS Connect clients that may connect to a node. The default is 0. If not specified, IMS Connect client may not connect to the machine being described.
This address is used by the IMSCONN subsystem internally between
IMSCONN and
IMSCONNH. The address is a string in standard internet URL format. For example:
//computer1:4001 designates port 4000 on machine computer.
The -d option is used to set server's trace level. If not set, the trace level is -1 by default, meaning, only error information will be put to trace log file. Available trace-level value is 0, 1, or 2:
ODBAPROX - is a socket server on z/OS and is to communicate with
Tuxedo ART for IMS servers through TCP/IP.
ODBA proxy is a socket server to communicate with Tuxedo ART for IMS servers through TCP/IP.
ODBAPROX is developed to communicate with the programs in Tuxedo ART for IMS and perform database operations on behalf of these programs
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 is used. It is a mandatory environment variable for
ARTICTL if MFS is used.
An environment variable required by ARTICTL to specify whether to translate user name to upper case or not. If it is set to
Y, all user name characters are translated to upper case. If it is set to
N or if it is not set, there is no translation.
|
|
|
|
|
|
|
Use cobcall with default CANCEL behavior.
|
|
Use cobcall with physical CANCEL behavior.
|
|
Use cobcall with logical CANCEL behavior, and physically cancel .dll code and shared object code as part of a logical cancel operation.
|
|
Use cobcall with logical CANCEL, and do not physically cancel .dll code and shared object code as part of a logical cancel operation.
|
|
Use cobcall without CANCEL behavior.
|
If set to "Y", BMP server exits after executing a BMP program. If set to "
N", BMP server remains live after executing a BMP program.
If this environment variable is not set, the default list (SIGSEGV,SIGILL,SIGBUS,SIGFPE), is used. If an illegal signal number is specified, it is ignored and a warning message is written in the
ULOG file. If a legal signal number which can’t be caught is specified (e.g.,
SIGKILL or
SIGSTOP), the server boot fails and warning message is written in the
ULOG file.
If set to ABORT, server
MPP/BMP aborts when an exception from the user application is caught the core file of the server may or may not be generated based on the system configuration.
If set to KEEP, the server is kept alive. If not set, the default value is
KEEP.
Specifies the logon screen directory, which must be a sub-directory in $IMSDIR. If not set, the default value is
sysmap, which means the logon screen in
$IMSDIR/sysmap is used. There is another logon screen defined in
$IMSDIR/sysmap2; the only difference between
sysmap2 and
sysmap is the positions for user name and password input fields. For more information about user defined logon screen, see the
readme file in
$IMSDIR/sysmap2.
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. It is a mandatory environment variable for COBOL-IT.
Used for DFSRRC00 to specify the timeout second value for
DFSRRC00 to wait for the
BMP/BMPT program response. It uses the following rules:
•
|
CEE3ABD/ ART3ABD is called (except when CEE3ABD is called in an MF environment).
|
•
|
Signal specified in ART_IMS_EXCEPTION_TO_CATCH or in default signal list ( ART_IMS_EXCEPTION_TO_CATCH is not set), is caught.
|
If IMS_DUMP_TYPE is not configured, the default value is
NONE - but if
ARTIMS_EXCEPTION_HANDLING is set to
ABORT,
SYSTEM_DUMP is enabled when the signal is caught. The dump types for all combinations are listed in
Table 21.
|
|
|
|
|
|
|
|
|
|
Both above COBOL_DUMP and SYSTEM_DUMP requirements.
|
Used for DFSRRC00 to specify all the environment variable names that need to be sent to
ARTIBMP server except all those environment variables with prefix "
DD_". All the environment variable's name should be separated with a comma. It should be set before
DFSRRC00 is launched.
If IMS_LONG_USERNAME is set to be
“Y”, the max 30 bytes username/password is used; otherwise, the traditional 8-byte username/password is used.
If IMS_PERF_ENABLE is not set, the performance behavior is set by using the
UBBCONFIG file
-V option.
If set to Y, at the start/end of a transaction/program in MPP/BMP servers a trace line is added to the program invocation log file in the following format:
transaction name,
program name,
Sstart time, Eend time,
group id,
server id.
Table 23 lists the commands and associated parameters that can be input on 3270 terminal and be processed by Tuxedo ART for IMS.
Table 24 shows an example configuration file with field names mapped from TRANSACT MACRO of IMS on z/OS
Table 25 shows an example configuration file with field names mapped from APPLCTN MACRO of IMS on z/OS.
Listing 7 shows a script example to create queue space and queues for your reference; you can customerize the script to adapt to the real requirement. For more information, see Oracle Tuxedo /Q guides.
Some imsdbs.desc field configurations are mapped from some DBD statement of IMS on z/OS. For persistent transactions that issue
ROLB or
ROLL, the retry count for creating the transaction queue should be set to a relatively large number (the largest number could up to 2147483647).
$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 number of [imspcb] sections with
LIST=YES can be (at most) 31. The maximum PCB numbers including
IOPCB is 32.
Note:
|
The [imspcb] sections with LIST=NO are not counted.
|
Table 28 shows an example configuration file with field names mapped from PCB statement for IMS on z/OS.
For SEGPGM_A2E,
SEGPGM_E2A and
SSAPGM_A2E,
KFAPGM_E2A:
2. SEGPGM_A2E and
SEGPGM_E2A.
SEGPGM_A2E and
SEGPGM_E2A must be both defined or both not defined together. When
SEGPGM_A2E and
SEGPGM_E2A are defined, the ODBA Plugin uses
SEGPGM_A2E/
SEGPGM_E2A to do segment data converting, not use the
$segname.desc to perform segment data converting even if there is
$segname.desc.
When SEGPGM_A2E and
SEGPGM_E2A are not defined, the ODBA plug-in uses the FIELDS definition in
$segname.desc to perform segment data converting.
When SSAPGM_A2E is defined, the ODBA plug-in uses the defined COBOL program to do qualified SSA converting for this segment.
When SSAPGM_A2E is not defined, the ODBA Program uses the
KEY Field type definition in
$segname.desc to convert the
KEY value in the SSA for this segment.
When KFAPGM_E2A is defined, the ODBA plug-in uses the defined COBOL program to do data converting for Key Feedback area for this segment.
If KFAPGM_E2A is not defined, ODBA program uses the
FBAFIELD definition in
$segname.desc to do data converting for Key feedback area for this segment.
$segname.desc defines the fields within a segment.
$segname.desc only exist for databases with access type of neither GSAM nor MSDB defined in
imsdbs.desc,
$segname.desc is located under
$ART_IMS_CONFIG/db/$dbname.
Table 31 shows the Field Definition mapping table according to field usage in the COBOL program.
At the completion of a retrieval or ISRT call, the Key Feedback Area is returned from ODBA Proxy. We reserve one special FIELD whose name is
FBAFIELD to convert Key Feedback Area in DB PCB.
This special FIELD(FBAFIELD) defined in
$segment must defined the format of the concatenated key of the segment. The Key FeedBack Area will be converted according to the definition of this field for the segname.
Listing 8 shows an example definition in
$segname.desc.
BYTES defines the total length of the KEY FeedBack Area, that is the concatenated key total length.
TYPE defines the concatenated key’s type. If the concatenated key has different type, the
TYPE should be set to
M.
FORMAT should define the concatenate. key format if the
TYPE=M.
If the special FIELD(FBAFIELD) is not defined in
$ segname.desc, the KEY FeedBack Area is converted as
TYPE C by default for the segname.
imsdebug.desc defines all program debugging info. (currently for COBOL program debugging only).
zostrans.desc file defines all transactions remaining on z/OS. All these transactions should only be called as sub-transactions, and only non-conversational transactions are supported now.
imsgenconf creates configurations for the transaction/applications listed in
IMS.WHITE Its format is as follows:
[TRANCODE] section: Defines the transaction codes in the black/white list. Each transaction key has at most 8 characters.
[APPPSB] section: Defines the
PSB name for batch application programs in the black/white list. Each
PSB key has at most 8 characters.
imsgenconf creates configurations for the transaction/applications that are not defined in
IMS.BLACK. Its format is as follows:
Defines the PSBNAME for batch application programs in the black/white list. Each
PSB key has at most 8 characters.
Tuxedo ART for IMS supports SYSIN/SYSOUT redirection for
ACCEPT/DISPLAY statement in Tuxedo ART for IMS batch COBOL program in Micro Focus COBOL environment. To support this, Tuxedo ART for IMS adds a new file handler named "
ARTEXTFH" (located at
$IMSDIR/coblib_mf/BMP).
This file handler is at $IMSDIR/coblib_mf/MPP. All these two file handler will be loaded by
ARTIBMP or
ARTIMPP servers. If the default file handler behavior is not suitable for special case, user could switch these two file handler files or replace with user specified file handler.
In C programs, STDIN/STDOUT/STDERR are redirected to the
SYSIN/SYSOUT/SYSOUT file. If
SYSIN is not defined or not accessiable, redirection is not initiated.
If SYSOUT is not defined or not accessiable,
STDOUT/STDERR is redirected to the
$APPDIR/SYSOUT file.
For COBOL-IT, only SUBSYS mode is supported. For Microfocus, there are seven supported COBOL modes:
3.
|
Start "anim" in the current or a new terminal; the " anim" should remain in waiting state.
|
•
|
Oracle Tuxedo ART for IMS Users Guide
|