startTransaction()

The vgLib.startTransaction() system function invokes a main program asynchronously and passes a record, with the following consequences:

Unlike the transfer or call statements, both of which call a program synchronously, vgLib.startTransaction() allows the calling program to continue to run at the same time as the called program.

If you are generating for Java™, you can override the program name in the record by specifying a program to start as a parameter in the function call.

Syntax

  vgLib.startTransaction(
    request ANY in
    [, prID INT or CHAR inOut
    [, termID INT or CHAR(4) inOut ]])

  vgLib.startTransaction(
    request ANY in
    [, progName CHAR inOut ])
request
The name of a basic record, which must have the following format:
  • The first 2 bytes (a SMALLINT or a BIN without decimals) contain the length of the data to be passed to the started transaction, plus 10 for the two fields (including this one) that are not passed.
  • The next 8 bytes (CHAR) also are not passed. The content depends on the target system; see the "Compatibility" section in this topic.
  • The remainder of the request record is passed.
prID
This argument is used only on CICS® and iSeries® COBOL platforms. See the "Compatibility" section in this topic.
termID
This argument is used only on CICS platforms. See the "Compatibility" section in this topic.
progName
The name of a program to be started asynchronously. This option is for Java only; see the "Compatibility" section in this topic.

Example

The following example shows the vgLib.startTransaction() function:

myRequest RequestPart;
myRequest.prefix = "18";
myRequest.progName = "MyProgrm";
myRequest.reqrec = "MyData";
vgLib.startTransaction(myRequest);

The record declaration accompanying this example of program code is as follows::

Record RequestPart type BasicRecord
    10 prefix SMALLINT;
    10 progName CHAR(8);
    10 reqrec CHAR(8);
end

Compatibility

Table 1. Compatibility considerations for vgLib.startTransaction()
Platform Issue
Java generation
  • A Java program can start only another Java program generated by EGL on the same machine, in a separate Java Virtual Machine (JVM). The default behavior is to start a program that resides in the same Java package; however, you can specify a different package by fully qualifying the progName. (Or you can change the asynchLink element in the linkage options part that is used to generate the invoking program.)
  • Bytes 3-10 of the request record contain the name of the default program to be started. If you specify progName, this argument overrides the program name in the request record. The size of the record passed cannot exceed 32767 bytes. The prID and termID parameters are ignored.
  • If you use V6 exception compatibility (see Using V6 exception compatibility), the following values are returned in sysVar.errorCode:
    00000000
    The new JVM was created and the record was passed successfully. That value can occur even if the invoked program failed to run.
    00000001
    A new JVM cannot be created or that an error occurred while passing the record.
CICS
  • The vgLib.startTransaction() function issues a CICS START command for the target transaction. The default behavior is to start a program that resides in the same CICS region; however, you can specify a different region by defining the asynchLink element in the linkage options part that is used when you generate the invoking program. The prID and termID parameters are ignored if the target transaction is started on a remote system.
  • Bytes 3-6 of the request record contain a transaction ID, and the next 4 bytes must be blanks. The size of the record passed cannot exceed 32767 bytes.
  • Depending on the value of the termID parameter, EGL issues the CICS START command with or without an associated device:
    • If termID is not specified, EGL associates the current terminal with the target transaction; specifically, EGL assigns the current terminal identifier to the TERMID option in the CICS START command.
    • If termID is specified and its value is not binary zeros, EGL associates the specified device (terminal or printer) with the target transaction; specifically, EGL assigns the value of termID to the TERMID option in the CICS START command but does not assign a value to the RTERMID option.

      Results are not predictable if the value in termID is the CICS terminal ID that is associated with the current transaction. To end the current transaction and start a new transaction at the current terminal, use the transfer to transaction or show statement rather than the vgLib.startTransaction system function.

    • If the value of the termID parameter is binary zeros, EGL associates no terminal with the target transaction; specifically, EGL assigns the value of the prID parameter to the RTERMID option in the CICS START command but does not assign a value to the TERMID option. In addition, the prID parameter is the printer ID that is used to initialize the converseVar.printerAssociation system variable in the target transaction. To set the termID CHAR field to binary zeros, use an assignment statement containing a hex literal for 4 bytes of binary zeros:
        myCHAR = x"00000000";
  • For more information about how the prID and termID parameters are used to initialize the printerAssociation in the target program, see "printerAssociation."
  • The target transaction must have PCT and PPT entries. If the first program in that transaction is not generated by EGL or VisualAge Generator, that program must issue a CICS RETRIEVE to get the passed work area and terminal information.
CICS (continued)
  • If you use V6 exception compatibility (see Using V6 exception compatibility), the following values can be returned in sysVar.errorCode:
    00000000
    Successful
    00000203
    Transaction ID is not valid
    00000205
    Terminal ID is not valid
    00000206
    Parameters is not valid
    00000207
    System ID is not valid
    00000208
    Link is out of service
    ffrrrrrr
    Another CICS error, where ff is the hexadecimal representation of EIBFN byte 0 and rrrrrr is the hexadecimal representation of EIBRCODE bytes 0-2
iSeries COBOL
  • The function starts a program on the same iSeries machine. EGL runtime provides support for this by means of two command language (CL) programs:
    CREATX
    This program performs the following actions:
    • Gets the current job number
    • Sends the user data to the data queue VGCREATX
    • Starts a new CREATXJOB, which starts the CL program CREATXPP
    CREATXPP
    This program performs the following actions:
    • Uses the previous job number as the key to retrieve data from the data queue VGCREATX
    • Calls the asynchronous CL program specified in the request record bytes 3 through 11
  • Bytes 3-10 of the request record contain the name of the program to be started. The size of the passed record cannot exceed 4095 bytes.
  • The prID parameter is an optional, 4-byte CHAR field that contains the value of the output queue used for the asynchronous job. The default value is VGEN. The output queue must be defined before the program runs converseVar.printerAssociation.
  • The termID parameter is ignored.
IMS/VS or IMS™ BMP
  • vgLib.startTransaction() can start a transaction only on the same IMS system. Bytes 3-10 of the request record contain the IMS transaction code. The size of the record passed cannot exceed 32765 bytes. The prID and termID parameters are ignored.
  • The function results in an insert to the modifiable alternate PCB. EGL converts the request record to the format needed for an IMS message by adding 2 to the length and inserting 2 bytes between the length and the transaction field. The transaction is started without an associated terminal.
  • The transaction that is started must be included in the system IMS system definition and must be defined as a nonconversational transaction. If the target transaction is not an EGL program, it must issue a GU call to the I/O PCB to retrieve the message.
  • If you use V6 exception compatibility (see Using V6 exception compatibility), the following values can be returned in sysVar.errorCode:
    00000000
    The invocation was successful.
    00000203
    The invocation failed, probably because of a transaction code that was not valid.
z/OS® batch This function is not supported.

Feedback