Writing a Program

This chapter describes structures used to save data and functions.

1. Structures

The following describes each COBOL structure used to save data.

File Description

TPSTATUS.cbl

Must be defined for the ATMI (Application-to-Transaction Monitor Interface) routine.

TPTYPE.cbl

Used to send and receive user data.

TPSVCDEF.cbl

Used to send and receive a message to and from the Tmax system.

TPINFDEF.cbl

Used in TPINITIALIZE() to connect to the Tmax system.

TPSVCRET.cbl

Used in TPRETURN() to display the service running status.

TPTRXDEF.cbl

Used in TXBEGIN() to set the transaction timeout.

TPCMTDEF.cbl

Used in TPSCMT() to set commit level characteristics.

TPAUTDEF.cbl

Used in TPCHKAUTH() for authentication.

TPPRIDEF.cbl

Used in TPSPRIO() and TPGPRIO() for adjusting message priorities.

TPTRXLEV.cbl

Used in TPGETLEV() to set a transaction level.

TPBCTDEF.cbl

Used in TPNOTIFY() and TPBROADCAST() for sending a unsolicited message.

FDLINFO.cbl

Used in FINIT(), FVSTOF(), and FVFTOS() to manage FDL buffers.

TPEVTDEF.cbl

Used to manage events for unsolicited messages of TPPOST(), TPSUBSCRIBE(), TPUNSUBSCRIBE(), and other functions.

TXSTATUS.cbl

Used to manage codes returned by a TX routine.

TXINFDEF.cbl

Used to save a TXINFORM call result.

1.1. TPSTATUS

The TPSTATUS structure must be defined for the ATMI (Application-to-Transaction Monitor Interface) routine. The following return values are used.

***************************************
* TPSTATUS.cbl
***************************************
05 TP-STATUS            PICS9(9) COMP-5.
88 TPOK                 VALUE 0.
88 TPEABORT             VALUE 1.
88 TPEBADDESC           VALUE 2.
88 TPEBLOCK             VALUE 3.
88 TPEINVAL             VALUE 4.
88 TPELIMIT             VALUE 5.
88 TPENOENT             VALUE 6.
88 TPEOS                VALUE 7.
88 TPEPERM              VALUE 8.
88 TPEPROTO             VALUE 9.
88 TPESVCERR            VALUE 10.
88 TPESVCFAIL           VALUE 11.
88 TPESYSTEM            VALUE 12
88 TPETIME              VALUE 13.
88 TPETRAN              VALUE 14.
88 TPEGOTSIG            VALUE 15.
88 TPERMERR             VALUE 16.
88 TPEITYPE             VALUE 17.
88 TPEOTYPE             VALUE 18.
88 TPERELEASE           VALUE 19.
88 TPEHAZARD            VALUE 20.
88 TPEHEURISTIC         VALUE 21.
88 TPEEVENT             VALUE 22.
88 TPEMATCH             VALUE 23.
88 TPEMAXVAL            VALUE 24.
05 TPEVENT              PICS9(9) COMP-5.
88 TPEV-NOEVENT         VALUE 0.
88 TPEV-DISCONIMM       VALUE 1.
88 TPEV-SENDONLY        VALUE 2.
88 TPEV-SVCERR          VALUE 3.
88 TPEV-SVCFAIL         VALUE 4.
88 TPEV-SVCSUCC         VALUE 5.
05 TPSVCTIMOUT          PICS9(9) COMP-5.
88 TPED-NOEVENT         VALUE 0.
88 TPEV-SVCTIMEOUT      VALUE 1.
88 TPEV-TERM            VALUE 2.
05 APPL-RETURN-CODE     PICS9(9) COMP-5.

1.2. TPTYPE

The TPTYPE structure is used to send and receive user data. REC-TYPE indicates the type of data. LEN indicates the length of the data.

***************************************
* TPTYPE.cbl
***************************************
05 REC-TYPE             PIC X(8).
88 X-OCTET              VALUE "X_OCTET".
88 X-COMMON             VALUE "X_COMMON".
05 SUB-TYPE             PIC    X(16).
05 LEN                  PIC    S9(9) COMP-5.
88 NO-LENGTH            VALUE 0.
05 TPTYPE-STATUS        PICS 9(9) COMP-5.
88 TPTYPEOK             VALUE 0.
88 TPTRUNCATE           VALUE 1.

1.3. TPSVCDEF

The TPSVCDEF structure is used to send and receive a message to and from the Tmax system.

***************************************
* TPSVCDEF.cbl
***************************************
05 COMM-HANDLE          PIC S9(9) COMP-5.
05 TPBLOCK-FLAG         PIC S9(9) COMP-5.
88 TPBLOCK              VALUE 0.
88 TPNOBLOCK            VALUE 1.
05 TPTRAN-FLAG          PIC S9(9) COMP-5.
88 TPTRAN               VALUE 0.
88 TPNOTRAN             VALUE 1.
05 TPREPLY-FLAG         PIC S9(9) COMP-5.
88 TPREPLY              VALUE 0.
88 TPNOREPLY            VALUE 1.
05 TPACK-FLAG           PIC S9(9) COMP-5 REDEFINES TPREPLY-FLAG.
88 TPNOACK              VALUE 0.
88 TPACK                VALUE 1.
05 TPTIME-FLAG          PIC S9(9) COMP-5.
88 TPTIME               VALUE 0.
88 TPNOTIME             VALUE 1.
05 TPSIGRSTRT-FLAG      PIC S9(9) COMP-5.
88 TPNOSIGRSTRT         VALUE 0.
88 TPSIGRSTRT           VALUE 1.
05 TPGETANY-FLAG        PIC S9(9) COMP-5.
88 TPGETHANDLE          VALUE 0.
88 TPGETANY             VALUE 1.
05 TPSENDRECV-FLAG      PIC S9(9) COMP-5.
88 TPSENDONLY           VALUE 0.
88 TPRECVONLY           VALUE 1.
05 TPNOCHANGE-FLAG      PIC S9(9) COMP-5.
88 TPCHANGE             VALUE 0.
88 TPNOCHANGE           VALUE 1.
05 TPSERVICETYPE-FLAG   PIC S9(9) COMP-5.
88 TPREQRSP             VALUE IS 0.
88 TPCONV               VALUE IS 1.
*
05 APPKEY               PIC S9(9) COMP-5.
05 CLIENTID             OCCURS 4 TIMES PIC S9(9) COMP-5.
05 SERVICE-NAME         PIC X(15).

1.4. TPINFDEF

The TPINFDEF structure is used in TPINITIALIZE() to connect to the Tmax system.

***************************************
* TPINFDEF.cbl
***************************************
05 USRNAME                  PIC X(30).
05 CLTNAME                  PIC X(30).
05 PASSWD                   PIC X(30).
05 GRPNAME                  PIC X(30).
05 NOTIFICATION-FLAG        PIC S9(9) COMP-5.
88 TPU-SIG                  VALUE 1.
88 TPU-DIP                  VALUE 2.
88 TPU-IGN                  VALUE 3.
05 ACCESS-FLAG              PIC S9(9) COMP-5.
88 TPSA-FASTPATH            VALUE 1.
88 TPSA-PROTECTED           VALUE 2.
05 DATALEN PICS9(9)         COMP-5.

1.5. TPSVCRET

The TPSVCRET structure is used in TPRETURN() to display the service running status.

***************************************
* TPSVCRET.cbl
***************************************
05 TP-RETURN-VAL         PIC S9(9) COMP-5.
88 TPSUCCESS             VALUE 0.
88 TPFAIL                VALUE 1.
88 TPEXIT                VALUE 2.
05 APPL-CODE             PIC S9(9) COMP-5.

1.6. TPTRXDEF

The TPTRXDEF structure is used in TXBEGIN() to set the transaction timeout.

***************************************
* TPTRXDEF.cbl
***************************************
05 T-OUT PICS9(9)     COMP-5 VALUE IS0.
05 TRANID             OCCURS 6 TIMES PICS9(9) COMP-5.

1.7. TPCMTDEF

The TPCMTDEF structure is used in TPSCMT() to set commit level characteristics.

***************************************
* TPCMTDEF.cbl
***************************************
05 CMT-FLAG                 PIC S9(9) COMP-5.
88 TP-CMT-LOGGED            VALUE 1.
88 TP-CMT-COMPLETE          VALUE 2.
05 PREV-CMT-FLAG            PIC S9(9) COMP-5.
88 PREV-TP-CMT-LOGGED       VALUE 1.
88 PREV-TP-CMT-COMPLETE     VALUE 2.

1.8. TPAUTDEF

The TPAUTDEF structure is used in TPCHKAUTH() for authentication.

***************************************
* TPAUTDEF.cbl
***************************************
05 AUTH-FLAG             PIC S9(9) COMP-5.
88 TPNOAUTH              VALUE 0.
88 TPSYSAUTH             VALUE 1.
88 TPAPPAUTH             VALUE 2.

1.9. TPPRIDEF

The TPPRIDEF structure is used in TPSPRIO() and TPGPRIO() for adjusting message priorities.

***************************************
* TPPRIDEF.cbl
***************************************
05 PRIORITY            PIC S9(9) COMP-5.
05 PRIO-FLAG           PIC S9(9) COMP-5.
88 TPABSOLUTE          VALUE 0.
88 TPRELATIVE          VALUE 1.

1.10. TPTRXLEV

The TPTRXLEV structure is used in TPGETLEV() to set the transaction level.

***************************************
* TPTRXLEV.cbl
***************************************
05 TPTRXLEV-FLAG         PIC S9(9) COMP-5.
88 TP-NOT-IN-TRAN        VALUE 0.
88 TP-IN-TRAN            VALUE 1.

1.11. TPBCTDEF

The TPBCTDEF structure is used in TPNOTIFY() and TPBROADCAST() for sending a unsolicited message.

***************************************
* TPBCTDEF.cbl
***************************************
05 TPBLOCK-FLAG         PIC S9(9) COMP-5.
88 TPBLOCK              VALUE 0.
88 TPNOBLOCK            VALUE 1.
05 TPTIME-FLAG          PIC S9(9) COMP-5.
88 TPTIME               VALUE 0.
88 TPNOTIME             VALUE 1.
05 TPSIGRSTRT-FLAG      PIC S9(9) COMP-5.
88 TPNOSIGRSTRT         VALUE 0.
88 TPSIGRSTRT           VALUE 1.
05 LMID                 PIC X(30).
05 USERNAME             PIC X(30).
05 CLTNAME              PIC X(30).

1.12. FDL-INFO

The FDL-INFO structure is used in FINIT(), FVSTOF(), and FVFTOS() to manage FDL buffers.

***************************************
* FDLINFO.cbl
***************************************
05 FDL-STATUS          PIC S9(9) COMP-5.
88 FOK                 VALUE 0.
88 FALIGNERR           VALUE 1.
88 FNOTFLD             VALUE 2.
88 FNOSPACE            VALUE 3.
88 FNOTPRES            VALUE 4.
88 FBADFLD             VALUE 5.
88 FTYPERR             VALUE 6.
88 FEUNIX              VALUE 7.
88 FBADNAME            VALUE 8.
88 FMALLOC             VALUE 9.
88 FSYNTAX             VALUE 10.
88 FFTOPEN             VALUE 11.
88 FFTSYNTAX           VALUE 12
88 FEINVAL             VALUE 13.
88 FBADTBL             VALUE 14.
88 FBADVIEW            VALUE 15.
88 FVFSYNTAX           VALUE 16.
88 FVFOPEN             VALUE 17.
88 FBADACM             VALUE 18.
88 FNOCNAME            VALUE 19.
*
05 FDL-LENGTH          PIC S9(9) COMP-5.
*
05 FDL-MODE            PIC S9(9) COMP-5.
88 FUPDATE             VALUE 1.
88 FCONCAT             VALUE 2.
88 FJOIN               VALUE 3.
88 FOJOIN              VALUE 4.
*
05 VIEWNAME            PIC X(33).

1.13. TPEVTDEF

The TPEVTDEF structure is used to manage events for unsolicited messages of TPPOST(), TPSUBSCRIBE(), TPUNSUBSCRIBE(), and other functions.

***************************************
* TPEVTDEF.cbl
***************************************
05 TPBLOCK-FLAG          PIC S9(9) COMP-5.
88 TPBLOCK               VALUE 0.
88 TPNOBLOCK             VALUE 1.
05 TPTRAN-FLAG           PIC S9(9) COMP-5.
88 TPTRAN                VALUE 0.
88 TPNOTRAN              VALUE 1.
05 TPREPLY-FLAG          PIC S9(9) COMP-5.
88 TPREPLY               VALUE 0.
88 TPNOREPLY             VALUE 1.
05 TPTIME-FLAG           PIC S9(9) COMP-5.
88 TPTIME                VALUE 0.
88 TPNOTIME              VALUE 1.
05 TPSIGRSTRT-FLAG       PIC S9(9) COMP-5.
88 TPNOSIGRSTRT          VALUE 0.
88 TPSIGRSTRT            VALUE 1.
05 TPEV-METHOD-FLAG      PIC S9(9) COMP-5.
88 TPEVNOTIFY            VALUE 0.
88 TPEVSERVICE           VALUE 1.
88 TPEVQUEUE             VALUE 2.
05 TPEV-PERSIST-FLAG PIC S9(9) COMP-5.
88 TPEVNOPERSIST         VALUE 0.
88 TPEVPERSIST           VALUE 1.
05 TPEV-TRAN-FLAG        PIC S9(9) COMP-5.
88 TPEVNOTRAN            VALUE 0.
88 TPEVTRAN              VALUE 1
*
05 EVENT-COUNT           PIC S9(9) COMP-5.
05 SUBSCRIPTION-HANDLE   PIC S9(9) COMP-5.
05 NAME-1                PIC X(31).
05 NAME-2                PIC X(31).
05 EVENT-NAME            PIC X(31).
05 EVENT-EXPR            PIC X(255).
05 EVENT-FILTER          PIC X(255).

1.14. TXSTATUS

The TXSTATUS structure is used to manage codes returned by a TX routine.

***************************************
* TXSTATUS.cbl
***************************************
05 TX-STATUS             PIC S9(9) COMP-5.
88 TX-NOT-SUPPORTED      VALUE 1.
* Normal execution
88 TX-OK                 VALUE 0.
* Normal execution
88 TX-OUTSIDE            VALUE -1.
* Application is in an RM local transaction
88 TX-ROLLBACK           VALUE -2.
* Transaction was rolled back
88 TX-MIXED              VALUE -3.
* Transaction was partially committed and partially
* rolled back
88 TX-HAZARD             VALUE -4.
* Transaction may have been partially committed and
* partially rolled back
88 TX-PROTOCOL-ERROR VALUE -5.
* Routine invoked in an improper context
88 TX-ERROR             VALUE -6.
* Transient error
88 TX-FAIL              VALUE -7.
* Fatal error
88 TX-EINVAL            VALUE -8.
* Invalid arguments were given
88 TX-COMMITTED         VALUE -9.
* The transaction was heuristically committed
88 TX-NO-BEGIN          VALUE -100.
* Transaction committed plus new transaction could not
* be started
88 TX-ROLLBACK-NO-BEGIN VALUE -102.
* Transaction rollback plus new transaction could not
* be started
88 TX-MIXED-NO-BEGIN    VALUE -103.
* Mixed plus new transaction could not be started
88 TX-HAZARD-NO-BEGIN   VALUE -104.
* Hazard plus new transaction could not be started.
88 TX-COMMITTED-NO-BEGIN VALUE -109.
* Heuristically committed plus transaction could not
* be started

1.15. TXINFDEF

The TXINFDEF structure is used to save a TXINFORM call result.

***************************************
* TXINFDEF.cbl
***************************************
05 XID-REC.

* XID record
10 FORMAT-ID             PIC S9(9) COMP-5.

* A value of -1 in FORMAT-ID means that the XID is null
10 GTRID-LENGTH         PIC S9(9) COMP-5.
10 BRANCH-LENGTH         PIC S9(9) COMP-5.
10 XID-DATA             PIC X(128).
05 TRANSACTION-MODE     PIC S9(9) COMP-5.

* Transaction mode settings
88 TX-NOT-IN-TRAN     VALUE 0.
88 TX-IN-TRAN                 VALUE 1.
05 COMMIT-RETURN                 PIC S9(9) COMP-5.

* Commit_return settings
88 TX-COMMIT-COMPLETED         VALUE 0.
88 TX-COMMIT-DECISION-LOGGED VALUE 1.
05 TRANSACTION-CONTROL         PIC S9(9) COMP-5.

* TRANSACTION-CONTROL settings
88 TX-UNCHAINED                 VALUE 0.
88 TX-CHAINED                 VALUE 1.
05 TRANSACTION-TIMEOUT         PIC S9(9) COMP-5.

* Transaction_timeout value
88 NO-TIMEOUT                 VALUE 0.
05 TRANSACTION-STATE             PIC S9(9) COMP-5.

* Transaction_state information
88 TX-ACTIVE                     VALUE 0.
88 TX-TIMEOUT-ROLLBACK-ONLY     VALUE 1.
88 TX-ROLLBACK-ONLY             VALUE 2.

2. Functions

The following describes each function used in a COBOL program.

Function Description

FINIT

Initializes a field buffer.

FVFTOS

Uses a COBOL structure to copy data in a field buffer.

FVSTOF

Transfers data from a C structure to a field buffer.

TP_SLEEP

Waits for data.

TPACALL

Asynchronously sends a service request.

TPCALL

Synchronously sends a service request and receives a response.

TPCANCEL

Cancels a response.

TPFORWARD

Forwards a service request to another service routine.

TPGETLEV

Checks the current transaction mode.

TPGETRPLY

Retrieves a response to a service that was asynchronously requested.

TPRETURN

Ends a Tmax service.

TPSVCSTART

Starts a Tmax service.

TPSVRDONE

Terminates a server process.

TPSVRINIT

Initializes a Tmax server.

TXBEGIN

Starts a global transaction.

TXCOMMIT

Commits a global transaction.

TXINFORM

Returns global transaction information.

TXROLLBACK

Rolls back a global transaction.

TXSETCOMMITRET

Sets the commit-return characteristic.

TXSETTIMEOUT

Sets the transaction-timeout characteristic.

TXSETTRANCTL

Sets the transaction-control characteristic.

2.1. FINIT

The FINIT function initializes a field buffer.

  • Usage

    01 FDL-BUFFER.
05 FDL-ALIGN     PIC S9(9) USAGE IS COMP.
05 FDL-DATA      PIC X(User-specified length).
01 FDL-REC
COPY FDLINFO.

CALL "FINIT"     USING FDL-BUFFER FDL-REC.
    Parameter Description

    FDL-BUFFER

    Record used for a field buffer. Four bytes must be allocated for the buffer.

    FDL-LENGTH IN FDL-REC

    Length of the record.

  • Return Value

    Result Description

    Success

    FDL-STATUS IN FDL-REC is set to FOK.

    Failure

    FDL-STATUS is set to a non-zero value.

  • Error

    When FINIT fails to execute, FDL-STATUS is set to the following value.

    Error Code Description

    [FNOSPACE]

    The field buffer size is insufficient to save data.

  • Related Function

    FVFTOS

2.2. FVFTOS

The FVFTOS function uses a COBOL structure to copy data from a field buffer and enters the data into a COBOL record.

  • Usage

    01 DATA-REC.
COPY User data.
01 FDL-BUFFER.
05 FDL-ALIGN PIC S9(9) USAGE IS COMP.
05 FDL-DATA PIC X(applen).
01 FDL-REC COPY FDLINFO.

CALL "FVFTOS" USING FDL-BUFFER DATA-REC FDL-REC.
CALL "FVFTOS32" USING FDL-BUFFER DATA-REC FDL-REC.
    Parameter Description

    FDL-BUFFER

    Pointer to a field buffer initialized by FINIT.

    DATA-REC

    Pointer to a C structure.

    VIEWNAME IN FDL-REC

    Name of a view that describes a COBOL record.

    Fields in a field buffer are copied to a structure according to element descriptions in VIEWNAME. If a field in the buffer has no corresponding field in a COBOL record, it is ignored.

    If an element in a COBOL record has no corresponding field in a field buffer, the element is set to NULL. To save fields in array format in a COBOL record, a record element must be defined with OCCURS. If the number of fields in a buffer is less than the number of record elements, the remaining elements are filled with the default values specified in the view file. If not, the remaining occurrences are ignored.

  • Return Value

    Result Description

    Success

    FDL-STATUS IN FDL-REC is set to FOK.

    Failure

    FDL-STATUS is set to a non-zero value.

  • Error

    When FVFTOS fails to execute, FDL-STATUS is set to one of the following values.

    Error Code Description

    [FBENOENT]

    Since a specified field key is not defined in FDLFILE, it cannot be used in a field buffer.

    [FBENOSPACE]

    The field buffer size is insufficient to save data.

    [FEINVAL]

    An input parameter value is invalid.

    [FBEBADFLD]

    An invalid field key is used. In general, this error code is set when a field key that is not compiled by the fdlc utility is used.

    [FBEBADSTRUCT]

    An invalid structure is used. In general, this error code is set when a structure that the Tmax system cannot recognize is used or a structure definition file is abnormally compiled.

  • Related Function

    FVSTOF

2.3. FVSTOF

The FVSTOF function transfers data from a C structure to a field buffer.

  • Usage

    01 DATA-REC.
COPY User data.
01 FDL-BUFFER.
05 FDL-ALIGN PIC S9(9) USAGE IS COMP.
05 FDL-DATA PIC X(applen).
01 FDL-REC
COPY FDLINFO.

CALL "FVSTOF" USING FDL-BUFFER DATA-REC FDL-REC.
CALL "FVSTOF32" USING FDL-BUFFER DATA-REC FDL-REC.
    Parameter Description

    DATA-REC

    COBOL record.

    FDL-BUFFER

    Record that includes a field buffer.

    FDL-REC

    View name for specifying a COBOL record.

    FDL-MODE IN FDL-REC

    Method for entering data into a field buffer.

    • FUPDATE

    • FOJOIN

    • FJOIN

    • FCONCAT

    The above methods operate in the same way as the C functions Fupdate(3), Fojoin(3), Fjoin(3), and Fconcat, respectively.

  • Return Value

    Result Description

    Success

    FDL-STATUS IN FDL-REC is set to FOK.

    Failure

    FDL-STATUS is set to a non-zero value.

  • Error

    When FVSTOF fails to execute, FDL-STATUS is set to one of the following values.

    Error Code Description

    [FBENOENT]

    Since a specified field key is not defined in FDLFILE, it cannot be used in a field buffer.

    [FBENOSPACE]

    The field buffer size is insufficient to save data.

    [FEINVAL]

    An input parameter value is invalid.

    [FBEBADFLD]

    An invalid field key is used. In general, this error code is set when a field key that is not compiled by the fdlc utility is used.

    [FBEBADSTRUCT]

    An invalid structure is used. In general, this error code is set when a structure that the Tmax system cannot recognize is used or a structure definition file is abnormally compiled.

    [FBEMALLOC]

    Failed to allocate a field buffer to memory due to a system error.

  • Related Function

    FVFTOS

2.4. TP_SLEEP

The TP_SLEEP function waits (sleeps) for data for the specified maximum wait time. If data arrives, it immediately returns a response. This function is used in a server and client.

  • Usage

    int TP_SLEEP (int sec, cbl_tpstatus_t *status)
    Parameter Description

    sec

    Maximum time to wait for data in seconds.

  • Return Value

    If data arrives within sec, a positive number is returned. If not, 0 is returned. If an error occurs, -1 is returned and tperrno is set.

  • Error

    When tp_sleep() fails to execute, tperrno is set to one of the following values.

    Error Code Description

    [TPESYSTEM]

    Tmax system error occurred. Detailed error information is recorded in the system log file.

    [TPEOS]

    Operating system error occurred.

  • Related Functions

    TPACALL, TPGETRPLY

2.5. TPACALL

The TPACALL function asynchronously sends a service request to a service defined in SERVICE-NAME IN TPSVCDEF-REC and returns without waiting for a response. The result can be retrieved using the TPGETRPLY function or cancelled using the TPCANCEL function.

If a service request is sent in transaction mode, a response to the request must be received.

  • Usage

    01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.

CALL "TPACALL" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

    • DATA-REC IN TPTYPE-REC is data to be sent and LEN is the data length. If DATA-REC is a variable-length record, LEN is ignored and generally set to 1.

      If REC-TYPE IN TPTYPE-REC is SPACES, DATA-REC and LEN are ignored and a request is sent without data. If REC-TYPE is STRING and LEN is 0, a request is sent without data.

      REC-TYPE and SUB-TYPE in DATA-REC must be supported by SERVICE-NAME.

    • The following values can be set in TPSVCDEF-REC.

      Setting Value Description

      TPBLOCK

      If TPACALL is used without TPBLOCK, a normal result is returned even when a called service does not exist or an incorrect result is returned. The error is returned when TPGETRPLY is called. Using TPBLOCK, the service status can be checked when calling TPACALL.

      TPNOTRAN

      If the TPACALL function caller requests SERVICE-NAME in transaction mode with TPNOTRAN, the SERVICE-NAME service is excluded from transaction mode.

      If a service that does not support transactions is called in transaction mode, TPNOTRAN must be used. Even if this value is set, transaction timeout remains in effect when TPACALL is called in transaction mode. If a service called with this value fails, the service immediately returns without waiting for a response to TPNOREPLY and does not affect the caller’s transaction. If a service is successfully called, TPOK is returned and COMM-HANDLE IN TPSVCDEF-RE is set to 0.

      If a function caller is in transaction mode, TPNOTRAN must be set to use TPNOREPLY. To check the service status for TPNOREPLY, TPNOTRAN and TPBLOCK must be set. If TPBLOCK is not set, an error is not returned even when a service is NRDY.

      TPNOBLOCK

      If the blocking status is set (e.g., if an internal buffer is full of outgoing messages) when TPNOBLOCK is set, a service request fails.

      If TPACALL is called without TPNOBLOCK, when the blocking status is not set, the function caller waits until the blocking status is released or timeout (transaction timeout or blocking timeout) occurs.

      TPNOTIME

      If TPNOTIME is set, the function caller ignores blocking timeout and waits until a response is received. If transaction timeout is set, the timeout applies.

      TPSIGRSTRT

      TPSIGRSTRT is used to allow a signal interrupt. When a system function call is interrupted, the system function call is reexecuted.

      If a signal interrupt occurs when TPSIGRSTRT is not set, the function fails and tperrno is set to TPGOTSIG.

  • Return Value

    Result Description

    Success

    TP-STATUS is set to TPOK.

    Failure

    TP-STATUS is set to an error code.

  • Error

    When TPACALL fails to execute, TP-STATUS is set to one of the following values.

    Error Code Description

    [TPEINVAL]

    An argument is invalid. For example, SERVICE-NAME is SPACES or TPSVCDEF-REC is invalid.

    [TPENOENT]

    The SERVICE-NAME service does not exist. The service cannot be requested.

    [TPEITYPE]

    REC-TYPE and SUB-TYPE are not supported.

    [TPELIMIT]

    The number of unhandled asynchronous service requests reached the maximum number. The caller’s service request is not sent.

    [TPETRAN]

    The SERVICE-NAME service does not support transactions. TPNOTRAN is not set.

    [TPETIME]

    Timeout occurred. If a function caller is in transaction mode, transaction timeout occurred and a transaction was rolled back. If the caller is not in transaction mode and both TPNOTIME and TPNOBLOCK are not set, blocking timeout occurred. If transaction timeout occurred, a new service request is sent and a response failure due to a [TPETIME] error is expected until the transaction is rolled back.

    [TPEBLOCK]

    Blocking status occurred when TPNOBLOCK was set.

    [TPEGOTSIG]

    A signal was received when TPSIGRSTRT was not set.

    [TPEPROTO]

    The TPNOREPLY service was called in transaction mode when TPNOTRAN was not set.

    [TPESYSTEM]

    Tmax system error occurred.

    [TPEOS]

    Operating system error occurred.

  • Related Functions

    TPCALL, TPCANCEL, TPGETRPLY

2.6. TPCALL

The TPCALL function synchronously sends a service request and receives a response. Calling this function is the same as consecutively calling TPACALL and then TPGETRPLY. TPCALL sends and receives a service request using SERVICE-NAME in TPSVCDEF-REC.

  • Usage

    01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 ITPTYPE-REC.
COPY TPTYPE.
01 IDATA-REC.
COPY User data.
01 OTPTYPE-REC.
COPY TPTYPE.
01 ODATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPCALL" USING TPSVCDEF-REC ITPTYPE-REC IDATA-REC OTPTYPE-REC
ODATA-REC TPSTATUS-REC.

    • IDATA-REC IN ITPTYPE-REC is data to be sent and LEN is the data length. If IDATA-REC is a variable-length record, LEN is ignored and generally set to 0.

      If REC-TYPE IN ITPTYPE-REC is SPACES, IDATA-REC and LEN are ignored and a request is sent without data. If ITPTYPE-REC is STRING and LEN is 0, a request is sent without data.

      REC-TYPE and SUB-TYPE in ITPTYPE-REC are must be supported by SERVICE-NAME. LEN in ODATA-REC must be specified to take into consideration the maximum length of data in ODATA-REC and ODATA-REC itself to send a response. If the same record is used to send and receive data, ODATA-REC must be REDEFINED to IDATA-REC.

    • If TPCALL is successfully executed, ODATA-REC receives a response with a length of LEN of OTPTYPE-REC. REC-TYPE includes the type of a response, and SUB-TYPE in OTPTYPE-REC includes the subtype of a response. If a response is larger than ODATA-REC, only data that fits in an ODATA-REC record is included. The remainder of the response is truncated and TPTRUNCATE is set. If LEN in OTPTYPE-REC is 0 when a response is successfully received, the response has no data and data is not received in ODATA-REC. If LEN in OTPTYPE-REC has 0 as an input value, it is an error.

    • The following values can be set in TPSVCDEF-REC.

      Setting Value Description

      TPNOTRAN

      If the TPACALL function caller requests SERVICE-NAME in transaction mode with TPNOTRAN, the SERVICE-NAME service is excluded from transaction mode.

      If a service that does not support transactions is called in transaction mode, TPNOTRAN must be used. Even if this value is set, transaction timeout remains in effect when TPACALL is called in transaction mode. If a service called with this value fails, a caller’s transaction is not affected.

      TPNOCHANGE

      In general, if the type of a received response buffer differs from that of a buffer indicated by ODATA-REC, the latter buffer type is changed to match the former buffer type. The type and subtype of responded records must be identical to REC-TYPE IN OTPTYPE-REC and SUB-TYPE IN OTPTYPE-REC respectively.

      If TPNOCHANGE is set, the type set in ODATA-REC cannot change.

      TPNOBLOCK

      If the blocking status is set (e.g., if an internal buffer is full of outgoing messages) when TPNOBLOCK is set, a service request fails.

      If TPACALL is called without TPNOBLOCK, when the blocking status is not set, the function caller waits until the blocking status is released or timeout (transaction timeout or blocking timeout) occurs.

      TPNOTIME

      If TPNOTIME is set, the function caller ignores blocking timeout and waits until a response is received. If transaction timeout is set, the timeout applies.

      TPSIGRSTRT

      TPSIGRSTRT is used to allow a signal interrupt. When a system function call is interrupted, the system function call is reexecuted.

      If a signal interrupt occurs when TPSIGRSTRT is not set, the function fails and tperrno is set to TPGOTSIG.

  • Return Value

    Result Description

    Success

    TP-STATUS is set to TPOK.

    When TP-STATUS is set to TPOK or TPESVCFAIL, APPL-RETURN-CODE in TPSTATUS-REC includes a value specified by an application and sent as a part of TPRETURN. If a response is larger than ODATA-REC, only data that fits in an ODATA-REC record is included. The remainder of the response is truncated and TPTRUNCATE is set.

    Failure

    TP-STATUS is set to an error code.

  • Error

    When TPCALL fails to execute, TP-STATUS is set to one of the following values.

    Error Code Description

    [TPEINVAL]

    An argument is invalid. For example, SERVICE-NAME is SPACES or TPSVCDEF-REC is invalid.

    [TPENOENT]

    The SERVICE-NAME service does not exist. The service cannot be requested.

    [TPEITYPE]

    REC-TYPE and SUB-TYPE are not supported.

    [TPEOTYPE]

    A caller cannot recognize the type or subtype of a buffer for received responses. When TPNOCHANGE is set, REC-TYPE and SUB-TYPE in ODATA-REC do not match the type and subtype of the buffer respectively. Both ODATA-REC and LEN in OTPTYPE-REC cannot change.

    If a caller requests a service in transaction mode, the transaction is rolled back because the response is ignored.

    [TPETRAN]

    The SERVICE-NAME service does not support transactions, and TPNOTRAN is not set.

    [TPETIME]

    Timeout occurred. If a function caller is in transaction mode, transaction timeout occurred and a transaction was rolled back. If the caller is not in transaction mode and both TPNOTIME and TPNOBLOCK are not set, blocking timeout occurred. If transaction timeout occurred, a new service request is sent and a response failure due to a [TPETIME] error is expected until the transaction is rolled back.

    [TPESVCFAIL]

    Through TPFAIL, TPRETURN is called by a service routine that sends a response to a service request because an application error occurred. If a service response is received, the response saved in ODATA-REC is available.

    Communication can be tried before a transaction is rolled back until transaction timeout occurs. When communication is normally handled, TPNOTRAN must be set. All jobs handled in a caller’s transaction mode are rolled back when a transaction is complete.

    [TPESVCERR]

    An error occurred because an invalid argument was passed when a service routine or TPRETURN was handled. As a result, no response data was returned, and ODATA-REC and LEN in OTPTYPE-REC cannot change.

    SVCTIMEOUT for each service can be set in the Tmax configuration file. If a service handling time exceeds SVCTIMEOUT, the service stops and returns TPESVCERR.

    [TPEBLOCK]

    Blocking status occurred when TPNOBLOCK was set.

    [TPEGOTSIG]

    A signal was received when TPSIGRSTRT was not set.

    [TPEPROTO]

    TPCALL was called in an inappropriate context.

    [TPESYSTEM]

    Tmax system error occurred. Detailed error information is recorded in the system log file.

    [TPEOS]

    Operating system error occurred.

2.7. TPCANCEL

The TPCANCEL function cancels a response by cancelling the COMM-HANDLE IN TPSVCDEF-REC call descriptor, which is returned by TPACALL. It cannot cancel a call descriptor of a service associated with a global transaction. If a service response is cancelled, the call descriptor is invalidated and all responses received through the descriptor are ignored.

  • Usage

    01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPCANCEL" USING TPSVCDEF-REC TPSTATUS-REC.

  • Return Value

    Result Description

    Success

    TP-STATUS is set to TPOK.

    Failure

    TP-STATUS is set to an error code.

  • Error

    When TPCANCEL fails to execute, TP-STATUS is set to one of the following values.

    Error Code Description

    [TPEBADDESC]

    COMM-HANDLE is an invalid descriptor.

    [TPETRAN]

    COMM-HANDLE is associated with the caller’s transaction. COMM-HANDLE remains valid, and the caller’s current transaction is not affected.

    [TPEPROTO]

    TPCANCEL was called in an inappropriate context.

    [TPESYSTEM]

    Tmax system error occurred. Detailed error information is recorded in the system log file.

    [TPEOS]

    Tmax system error occurred. Detailed error information is recorded in the system log file.

    Or an operating system error occurred.

  • Related Functions

    TPACALL

2.8. TPFORWARD

The TPFORWARD function forwards a service request to another service routine.

TPFORWARD stops processing the service it is handling and transfers a client request to another service. TPFORWARD operates like TPRETURN because it includes EXIT PROGRAM. Like TPRETURN, TPFORWARD must be called within a service routine controlled by the Tmax system to be returned to the Tmax system. TPFORWARD cannot be called in a conversational service.

If a service routine is in transaction mode, TPFORWARD completes when a transaction coordinator finishes a transaction by executing TXCOMMIT or TXROLLBACK. If a transaction starts using TXBEGIN in the service routine, the transaction must be completed using TXCOMMIT or TXROLLBACK before TPFORWARD is called. All services connected with TPFORWARD must be in transaction mode, or none can be in transaction mode.

A service that received a request from TPFORWARD sends a response to the client that first requested a service using TPRETURN. TPFORWARD makes another server process send a response to the waiting requester. It can be used in multiple nodes. TPFORWARD must be called after responses to all services requested by a service routine are received. Call descriptors for unreceived responses are invalidated and related requests are not transferred.

Since a service routine creator cannot acquire control again after calling TPFORWARD, TPSIGRSTRT is used to send implicitly defined blocking. Although a signal suspended the execution of TPFORWARD, executing TPFORWARD is retried. Even though there is blocking, the execution is retried until timeout occurs. TPSVCDEF-REC is currently not used and its setting is ignored.

  • Usage

    01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
COPY TPFORWAR REPLACING TPSVCDEF-REC BY TPSVCDEF-REC
            TPTYPE-REC BY TPTYPE-REC
DATA-REC BY DATA-REC
TPSTATUS-REC BY TPSTAUS-REC

    • A service routine sends a request to a service defined in SERVICE-NAME using data saved in DATA-REC, and the service routine does not receive a response. The routine returns to the Tmax system after the request is sent. The server can then handle another job. Since TPFORWARD does not receive a response from a requester, a request can be sent to any service without a special error.

    • DATA-REC IN TPTYPE-REC is data to be sent and LEN is the data length. If DATA-REC is a variable-length record, LEN is ignored and generally set to 0.

      If REC-TYPE in TPTPE-REC is SPACES, DATA-REC and LEN are ignored and zero-length data is sent.

  • Return Value

    A service routine does not return any value to a caller (Tmax system), and TP-STATUS is not set.

  • Error

    When TPFORWARD fails to execute, tperrno is set to one of the following values.

    Error Code Description

    [TPESVCERR]

    An error occurred while handling a service routine or TPRETURN. As a result, no response data is returned and ODATA-REC and LEN in OTPTYPE-REC cannot change.

    [TPETIME]

    Timeout occurred while handling a service routine or sending a request.

  • Related Functions

    TPRETURN

2.9. TPGETLEV

The TPGETLEV function checks the current transaction mode. Currently, two transaction modes are available: TP-NOT-IN-TRAN and TP-IN-TRAN.

  • Usage

    01 TPTRXLEV-REC.
COPY TPTRXLEV.
01 TPSTATUS-REC.
COPY TPSTATUS.

CALL "TPGETLEV" USING TPTRXLEV-REC TPSTATUS-REC.

  • Return Value

    When TPGETLEV successfully executes, TP-STATUS is set to TPOK and TPTRXLEV-REC is set to TP-IN-TRAN if in transaction mode or set to TP-NOT-IN-TRAN if not in transaction mode.

2.10. TPGETRPLY

The TPGETRPLY function receives a response to a service that was asynchronously requested by TPACALL.

TPGETRPLY waits for a response until a response corresponding to COMM-HANDLE arrives or timeout occurs. In general, COMM-HANDLE becomes invalid after a response is received.

  • Usage

    01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.

CALL "TPGETRPLY" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

    • If data is successfully received, LEN is the length of actual data saved in DATA-REC.

      If LEN is 0, a response was not received and the ODATA-REC buffer indicated by LEN does not change. Zero cannot be used in LEN as an INPUT. If a response is larger than DATA-REC, only data that fits DATA-REC is included. The remainder of the response is truncated and TPTRUNCATE is set.

    • REC-TYPE includes the type while SUB-TYPE in OTPTYPE-REC includes the subtype of the sent data.

    • The following values can be set in TPSVCDEF-REC.

      Setting Value Description

      TPGETANY

      COMM-HANDLE in TPSVCDEF-REC, specified by an input value, is ignored, and a receivable response is returned.

      COMM-HANDLE is a call descriptor for a response. If there is no response, TPGETRPLY generally waits for a response.

      TPNOCHANGE

      If the type of a received response buffer differs from that of a buffer indicated by REC-TYPE, the buffer type in ODATAREC is changed to match the received response buffer type. If TPNOCHANGE is set, the type of a buffer indicated by REC-TYPE cannot change. The type and subtype of the received response buffer must be identical to those of the buffer indicated by REC-TYPE.

      TPNOBLOCK

      If TPNOBLOCK is set, a function caller does not wait for a response. If there is a receivable response, it is returned. If TPNOBLOCK is not set and there is no receivable response, a function caller waits until a response arrives or timeout (transaction timeout or blocking timeout) occurs.

      TPNOTIME

      If TPNOTIME is set, a function caller ignores blocking timeout and waits for a response until it is received. If TPGETRPLY is used in transaction mode, transaction timeout applies.

      TPSIGRSTRT

      TPSIGRSTRT is used to allow a signal interrupt. When a system function call is interrupted, the call is reexecuted.

  • Return Value

    Result Description

    Success

    Returns 1. The APPL-RETURN-CODE global variable, which is returned by TPRETURN, is defined in an application if TPGETRPLY is successfully returned or TP-STATUS is set to [TPESVCFAIL].

    Failure

    Returns -1. TP-STATUS is set to an error code.

  • Error

    When TPGETRPLY fails to execute, TP-STATUS is set to one of the following values.

    Error Code Description

    [TPEINVAL]

    An argument is invalid. For example, SERVICE-NAME is SPACES or TPSVCDEF-REC is invalid.

    [TPEBADDESC]

    COMM-HANDLE is an invalid descriptor.

    [TPEOTYPE]

    A caller cannot recognize the type or subtype of a buffer for received responses. When TPNOCHANGE is set, REC-TYPE and SUB-TYPE in ODATA-REC do not match the type and subtype of the buffer respectively. Both ODATA-REC and LEN in OTPTYPE-REC cannot change. If a caller requests a service in transaction mode, the transaction is rolled back because the response is ignored.

    [TPETIME]

    Timeout occurred. If a function caller is in transaction mode, transaction timeout occurred and a transaction was rolled back. If the caller is not in transaction mode and both TPNOTIME and TPNOBLOCK are not set, blocking timeout occurred.

    DATA-REC contents and LEN cannot change. If transaction timeout occurred, a new service request is sent and a response failure due to a [TPETIME] error is expected until the transaction is rolled back.

    [TPESVCFAIL]

    Through TPFAIL, TPRETURN is called by a service routine that sends a response to a service request because an application error occurred. If a service response is received, the response saved in DATA-RECDP is available. If a function caller is in transaction mode, the transaction is rolled back.

    Communication can be tried before a transaction is rolled back until transaction timeout occurs. When communication is normally handled, TPNOTRAN must be set. All jobs handled in a caller’s transaction mode are rolled back when a transaction is complete.

    [TPESVCERR]

    An invalid descriptor was used or XA operation failed in transaction mode. (TXBEGIN, TXCOMMIT, TXROLLBACK)

    [TPEBLOCK]

    Blocking status occurred when TPNOBLOCK was set. The descriptor is valid.

    [TPGOTSIG]

    A signal was received without setting TPSIGRSTRT.

    [TPEPROTO]

    TPGETRPLY was called in an inappropriate context.

    [TPESYSTEM]

    Tmax system error occurred.

    [TPEOS]

    Operating system error occurred.

  • Related Functions

    TPACALL, TPCANCEL, TPRETURN

2.11. TPRETURN

The TPRETURN function ends a Tmax service, indicating that the service routine is complete. This function plays the same role as the EXIT PROGRAM statement. If it is called, a service routine is returned to the Tmax system.

To successfully return a service routine to the Tmax system, it is recommended to call TPRETURN within a service routine controlled by the Tmax system. If a service routine is in automatic transaction mode and a client that calls a service does not explicitly start a transaction (i.e., if the client does not use TXBEGIN), TPRETURN commits a transaction (if TPSUCCESS is set) or rolls back the transaction (if TPFAIL is set). A service can be called multiple times as a part of a global transaction. Therefore, a transaction is not fully committed or rolled back until the client that started the transaction with TXBEGIN completes it by calling TXCOMMIT or TXROLLBACK.

TPRETURN sends a service response message. If a program waits for a response by calling TPCALL, TPGETRPLY, or TPRECV, it receives the response through a buffer after TPRETURN is successfully executed. If the TPRETURN call fails, [TPESVCERR] error or TPEV_SVCERR event is returned to a service routine and the program, depending on service characteristics.

  • Usage

    01 TPSVCRET-REC.
COPY TPSVCRET.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
COPY TPRETURN REPLACING TPSVCRET-REC BY TPSVCRET-REC
TPTYPE-REC BY TPTYPE-REC
DATA-REC BY DATA-REC
TPSTATUS-REC BY TPSTATUS-REC.

    • The following values can be set in TP-RETURN-VAL. Other values are treated as TPFAIL.

      Setting Value Description

      TPSUCCESS

      A service completed successfully. If data exists and an error does not occur while executing TPRETURN, the data is transferred.

      If a caller is in transaction mode, a part of a transaction can be committed. When the transaction is complete, if other services in the transaction completed successfully and can be committed, the transaction is committed. If a single service fails, the transaction is rolled back. A TPRETURN call does not indicate that an entire transaction is complete.

      Although a caller calls TPRETURN with TPSUCCESS, if a response exists, a conversational communication connection exists, or a job in a service rolls back a transaction, the service fails, and a relevant message is sent. A response receiver receives a [TPESVCERR] or TPEV_SVCERR event. If a transaction is rolled back within a service routine, TP-RETURN-VAL is set to TPFAIL.

      If TPRETURN is returned with TPSUCCESS in a conversational service, the TPEV_SVCSUCC event occurs.

      TPFAIL

      A service ended because an application failed. An error is returned to the program that receives a response. A call for receiving a response fails, and the receiver receives a [TPSVCFAIL] or TPEV_SVCFAIL event.

      If a caller is in transaction mode and a transaction is an autotransaction, TPRETURN rolls back the transaction. It is possible that the transaction is already in rollback status. Data cannot be sent with this value.

      TPEXIT

      TPEXIT is used to forcibly terminate a server process when a called service returns. A process terminated with TPEXIT can be restarted by TMM if RESTART is set to Y.

      TPDOWN

      Similar to TPEXIT. However, a process terminated with TPDOWN cannot be restarted by TMM.

    • APPL-CODE is a return code value defined by a user in an application and is sent to a program that receives a service response. The code is sent regardless of the TP-RETURN-VAL value as long as a response is successfully sent to a client (i.e., as long as a receiving call returns success or [TPSVCFAIL] or receives the TPEV_SVCSUCC or TPEV_SVCFAIL event). If a response is successfully sent to a client regardless of the TP-RETURN-VAL value, the code is sent. Data in APPL-CODE is available because it was transferred to APPL-RETURN-CODE in TPSTATUS-REC.

    • DATA-REC is data to be sent and LEN is the length of the data. If the data is NULL, LEN is ignored. In this case, if a program that called a service waits for a response, it receives a response without data. If the program does not wait for a response, TPRETURN discards any data and returns without a response.

      If DATA-REC indicates a variable-length buffer, LEN is ignored and generally set to 0. If REC-TYPE is SPACES, DATA-REC and LEN are ignored. If DATA-REC indicates a buffer with a length that must be specified, LEN cannot be 0. If REC-TYPE is STRING and LEN is 0, a request is sent without data.

  • Return Value

    A service routine does not return any value to the Tmax system, which is the caller. The routine ends when TPRETURN is used (contains EXIT PROGRAM).

    If a service routine does not use TPRETURN but uses the EXIT PROGRAM statement to directly return, a service returns a service error to the service requester. If TPRETURN is used outside of a service routine (e.g., in a routine that is not a service), it returns without doing anything. If a server is in transaction mode, the transaction is rolled back.

  • Error

    Since TPRETURN ends a service routine, an error that occurred while handling arguments cannot be sent to a caller service routine.

    In this case, TP-STATUS is set to [TPESVCERR] in the program that receives a service result through synchronous or asynchronous communication (i.e., using TPCALL or TPGETRPLY respectively). A TPEV_SVCERR event occurs in a program that receives a service result through conversational communication (i.e., using TPSEND or TPRECV).

  • Related Functions

    TPCALL, TPGETRPLY

2.12. TPSVCSTART

The TPSVCSTART function starts a Tmax service. This function is a Tmax system routine that is used first when creating a service routine.

If any other call is issued before calling TPSVCSTART in a service routine, an error occurs. TPVCSTART is used to retrieve arguments and the data of a service. TPVCSTART also allows a request received through TPCALL or TPACALL to be used by a service.

  • Usage

    01 TPSVCDEF-REC.
COPY TPSVCDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TPSVCSTART" USING TPSVCDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

  • Return Value

    Result Description

    Success

    TP-STATUS is set to TPOK. If the length of a received message is larger than defined LEN, only data that fits LEN is saved in DATA-REC and the remainder of the message is truncated and TPTRUNCATE is set.

    Failure

    TP-STATUS is set to an error code.

  • Error

    When TPSVCSTART fails to execute, TP-STATUS is set to one of the following values.

    Error Code Description

    [TPEINVAL]

    An argument is invalid.

    [TPEPROTO]

    TPSVCSTART was called in an inappropriate context.

    [TPESYSTEM]

    Tmax system error occurred.

    [TPEOS]

    Operating system error occurred.

  • Related Functions

    TPSVRINIT, TPSVRDONE, TXBEGIN, TPCALL

2.13. TPSVRDONE

The TPSVRDONE function terminates a server process. This function is called by a Tmax application server after all service requests are complete but before the process is terminated. While this routine executes, a server process is still a part of a system but does not support a service. Therefore, Tmax communication can be performed and transactions can be defined in this routine.

If an application does not provide TPSVRDONE, the default (TPSVRDONE) routine provided by Tmax is called. The default TPSVRDONE calls TXCLOSE and USERLOG to announce that a server is about to be terminated if the server is included in a server group that handles transactions. If either TPRETURN or TPFORWARD is called in TPSVRDONE, the routine returns without doing anything.

If TPSVRDONE maintains a conversational connection, waits for an asynchronous response, or returns in transaction mode, Tmax ends the conversational connection, ignores the asynchronous response, terminates a transaction, and a server is immediately terminated.

  • Usage

    01 TPSTATUS-REC.
COPY TPSTATUS.

PROCEDURE DIVISION.
* User code
EXIT PROGRAM.

  • Related Functions

    TPSVRINIT

2.14. TPSVRINIT

The TPSVRINIT function initializes a Tmax server. This function is called by the Tmax system while initializing a Tmax server.

TPSVRINIT is called after a process starts but before handling any services. Therefore, Tmax communication is allowed and transactions can be defined in this routine. If an application does not provide TPSVRINIT, the default (TPSVRINIT) routine provided by Tmax is called. The default TPSVRINIT calls TXOPEN and USERLOG to announce that a server successfully started if the server was included in the server group that handles transactions.

An application command line option (CLOPT) is sent through ARGC and ARGV. ARGC expresses the number of parameters and ARGV contains the arguments, which are separated by a SPACE character.

If either TPRETURN or TPFORWARD is called in TPSVRDONE, the routine returns without doing anything.

  • Usage

    LINKAGE SECTION.
01 CMD-LINE.
05 ARGC PIC 9(4) COMP-5.
05 ARGV.
10 ARGS PIC X OCCURS 0 TO 9999 DEPENDING ON ARGC.
01 TPSTATUS-REC.
COPY TPSTATUS.

PROCEDURE DIVISION USING CMD-LINE TPSTATUS-REC.
* User code
EXIT PROGRAM.

  • Return Value

    Result Description

    Success

    TP-STATUS is set to TPOK. A service can successfully receive a request.

    Failure

    TP-STATUS is set to -1. A server is terminated and cannot receive any service requests.

  • Related Functions

    TPSVRDONE

2.15. TXBEGIN

The TXBEGIN function starts a global transaction. The caller of this function goes into transaction mode.

In the Tmax system, a transaction is a logical unit that makes all tasks succeed or fail. A calling process must be connected to a resource manager using TXOPEN before starting a transaction. If the caller is already in transaction mode or TXOPEN has not been called, TXBEGIN fails and returns [TX-PROTOCOL-ERROR].

Once a transaction starts, a calling process must call TPCOMMIT or TPROLLBACK to complete the current transaction. Additionally, there are chaining transactions that do not explicitly call TXBEGIN to start a transaction. For more information, refer to TPCOMMIT and TPROLLBACK.

  • Usage

    01 TPTRXDEF-REC.
COPY TPTRXDEF.
CALL "TXBEGIN" USING TPTRXDEF-REC.

  • Return Value

    Result Description

    Success

    TX-STATUS is set to TX-OK.

    Failure

    TX-STATUS is set to an error code.

  • Error

    When TXBEGIN fails to execute, TX-STATUS is set to one of the following values.

    Error Code Description

    [TX-OUTSIDE]

    A transaction manager could not start a global transaction because the current calling process is participating in an external global transaction. After related jobs are complete, a global transaction can be started. The currently participating transaction is not affected.

    [TX-PROTOCOL-ERROR]

    TXBEGIN was called in an inappropriate context. E.g., a caller is already in transaction mode. The current transaction is not affected.

    [TX-ERROR]

    A transient error occurred while a transaction manager or a resource manager started a transaction. After this error returns, the caller is no longer in transaction mode. The reason for this error varies according to product characteristics.

    [TX-FAIL]

    A critical error occurred. A transaction manager or a resource manager can no longer handle jobs for the application. After this error returns, the caller is no longer in transaction mode. The reason for this error differs according to product characteristics.

  • Related Functions

    TPROLLBACK, TPCOMMIT, TPGETLEV

2.16. TXCOMMIT

The TXCOMMIT function commits a global transaction.

If the transaction-control characteristic is TX-UNCHAINED, the caller is no longer in transaction mode when TXCOMMIT returns. If the characteristic is TX-CHAINED, the caller remains in transaction mode for a new transaction when TXCOMMIT returns. If TXCOMMIT successfully executes, it returns TX-RETURN-STATUS.

  • Usage

    DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.

PROCEDURE DIVISION.
CALL "TXCOMMIT" USING TX-RETURN-STATUS.

  • Return Value

    Result Description

    Success

    Returns a non-negative TX-OK.

    Failure

    Returns TX-STATUS, which is set to a negative error code.

  • Error

    When TXCOMMIT fails to execute, TX-STATUS is set to one of the following values.

    Error Code Description

    [TX-NO-BEGIN]

    A transaction was successfully committed. However, a new transaction could not start and the caller is no longer in transaction mode. This value can be set only when the transaction-control characteristic is TX-CHAINED.

    [TX-ROLLBACK]

    A transaction was rolled back. If the transaction-control characteristic is TX-CHAINED, a new transaction starts.

    [TX-ROLLBACK-NO-BEGIN]

    A transaction was rolled back. A new transaction could not start and the caller is no longer in transaction mode. This value can be set only when the transaction-control characteristic is TX-CHAINED.

    [TX-MIXED]

    A transaction was partially committed and partially rolled back. If the transaction-control characteristic is TX-CHAINED, a new transaction starts.

    [TX-MIXED-NO-BEGIN]

    A transaction was partially committed and partially rolled back. A new transaction could not start and the caller is no longer in transaction mode. This value can be set only when the transaction-control characteristic is TX-CHAINED.

    [TX-HAZARD]

    A transaction may have been partially committed and partially rolled back due to an error. If the transaction-control characteristic is TX-CHAINED, a new transaction starts.

    [TX-HAZARD-NO-BEGIN]

    A transaction may have been partially committed and partially rolled back due to an error. A new transaction could not start and the caller is no longer in transaction mode. This value can be set only when the transaction-control characteristic is TX-CHAINED.

    [TX-PROTOCOL-ERROR]

    TXCOMMIT was called in an inappropriate context. E.g., a caller is not in transaction mode. The status of the caller associated with the transaction does not change.

    [TX-FAIL]

    A critical error occurred. A transaction manager or a resource manager can no longer handle jobs for an application. The status of the caller associated with the transaction is unknown. The reason for this error differs according to product characteristics.

  • Related Functions

    TXBEGIN, TXSETCOMMITRET, TXSETTRANCTL, TXSETTIMEOUT

2.17. TXINFORM

The TXINFORM function returns global transaction information using TX-INFO-AREA.

If TXINFORM executes in transaction mode, TX-IN-TRAN is set, a branch identifier of the current transaction is saved in XID-REC, and TRANSACTION-STATE is set to the current transaction status. If the caller is not in transaction mode, TX-NOT-IN-TRAN is set and NULL XID is saved in XID-REC.

Regardless of whether a caller is in transaction mode, COMMIT-RETURN, TRANSACTION-CONTROL, and TRANSACTION-TIMEOUT (in seconds) have the current settings.

A returned transaction timeout value is used after the next transaction starts. Therefore, the value may not apply to the current global transaction of a caller because TRANSACTION-TIMEOUT can be changed by calling TXSETTIMEOUT after the current transaction starts.

  • Usage

    DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.
01 TX-INFO-AREA.
COPY TXINFDEF.

PROCEDURE DIVISION.
CALL "TXINFORM" USING TX-INFO-AREA, TX-RETURN-STATUS.

  • Return Value

    Result Description

    Success

    Returns a non-negative TX-OK. If a caller is in transaction mode, 1 is returned. If not in transaction mode, 0 is returned.

    Failure

    Returns TX-STATUS that is set to a negative error code.

  • Error

    When TXINFORM fails to execute, TX-STATUS is set to one of the following values.

    Error Code Description

    [TX-PROTOCOL-ERROR]

    TXINFORM was called in an inappropriate context. E.g., a caller does not call TXOPEN yet.

    [TX-FAIL]

    A critical error occurred. A transaction manager can no longer handle jobs for an application. The reason for this error differs according to product characteristics.

  • Related Functions

    TXOPEN, TXSETCOMMITRET, TXSETTRANCTL, TXSETTIMEOUT

2.18. TXROLLBACK

The TXROLLBACK function rolls back a global transaction. If the transaction-control characteristic (refer to TXSETTRANCTL) is TX-UNCHAINED, the caller is no longer in transaction mode when TXROLLBACK returns. If the characteristic is TX-CHAINED, the caller remains in transaction mode for a new transaction when TXROLLBACK returns.

  • Usage

    01 TPTRXDEF-REC.
COPY TPTRXDEF.
01 TPSTATUS-REC.
COPY TPSTATUS.
CALL "TXROLLBACK" USING TPTRXDEF-REC.

  • Return Value

    Result Description

    Success

    TX-STATUS is set to TP-OK.

    Failure

    TX-STATUS is set to a negative error code.

  • Error

    When TXROLLBACK fails to execute, TX-STATUS is set to one of the following values.

    Error Code Description

    [TX-NO-BEGIN]

    A transaction was rolled back. A new transaction could not start and the caller is no longer in transaction mode. This value can be set only when the transaction-control characteristic is TX-CHAINED.

    [TX-MIXED]

    A transaction was partially committed and partially rolled back. If the transaction-control characteristic is TX-CHAINED, a new transaction starts.

    [TX-MIXED-NO-BEGIN]

    A transaction was partially committed and partially rolled back. A new transaction could not start and the caller is no longer in transaction mode. This value can be set only when the transaction-control characteristic is TX-CHAINED.

    [TX-HAZARD]

    A transaction was partially committed and partially rolled back due to an error. If the transaction-control characteristic is TX-CHAINED, a new transaction starts.

    [TX-HAZARD-NO-BEGIN]

    A transaction was partially committed and partially rolled back due to an error. A new transaction could not start and the caller is no longer in transaction mode. This value can be set only when the transaction-control characteristic is TX-CHAINED.

    [TX-COMMITTED]

    A transaction was heuristically committed. If the transaction-control characteristic is TX-CHAINED, a new transaction starts.

    [TX-COMMITTED-NO-BEGIN]

    A transaction was heuristically committed. A new transaction could not start and the caller is no longer in transaction mode. This value can be set only when the transaction-control characteristic is TX-CHAINED.

    [TX-PROTOCOL-ERROR]

    TXROLLBACK was called in an inappropriate context. E.g., a caller is not in transaction mode. The status of the caller associated with the transaction does not change.

    [TX-FAIL]

    A critical error occurred. A transaction manager or a resource manager can no longer handle jobs for an application. The status of the caller associated with the transaction is unknown. The reason for this error differs according to product characteristics.

  • Related Functions

    TXBEGIN, TPCOMMIT, TPGETLEV, TPACALL

2.19. TXSETCOMMITRET

The TXSETCOMMITRET function sets the commit-return characteristic in COMMIT-RETURN. The setting determines the way TXCOMMIT returns control to its caller. TXSETCOMMITRET can be called regardless of the mode its caller is in. This setting remains in effect until changed by a subsequent call to TXSETCOMMITRET.

  • Usage

    DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.
01 TX-INFO-AREA.
COPY TXINFDEF.

PROCEDURE DIVISION.
CALL "TXSETCOMMITRET" USING TX-INFO-AREA TX-RETURN-STATUS.

    The following commit-return characteristic values can be set in COMMIT-RETURN.

    Setting Value Description

    TX-COMMIT-DECISION-LOGGED

    TXCOMMIT returns after a commit decision is logged in the first phase of the two-phase commit protocol but before the second phase is complete.

    This setting allows a faster response to a TXCOMMIT caller. The transaction may have a heuristic result. In this case, a caller cannot know about the situation from the code returned from TXCOMMIT. In a normal case, a transaction participant that plans to commit a transaction in the first phase commits the transaction in the second phase. A heuristic result can occur if the second phase is never completed due a lengthy network or node failure.

    A transaction manager can use an option to determine whether to support this value. It returns [TX-NOT-SUPPORTED] to indicate that this value is not supported.

    TX-COMMIT-COMPLETED

    (Default value)

    TXCOMMIT returns after two-phase commit is fully complete.

    This setting sends a return code to a TXCOMMIT caller indicating that a transaction had or may have had a heuristic result. A transaction manager can use an option to determine whether to support this value. It returns [TX-NOT-SUPPORTED] to indicate that this value is not supported.

  • Return Value

    If TXSETCOMMITRET successfully executes, it returns a non-negative TX-OK.

    If COMMIT-RETURN is not set to neither TX-COMMIT-COMPLETED nor TX-COMMIT-DECISION-LOGGED, TXSETCOMMITRET returns a non-negative [TX-NOT-SUPPORTED]. The current commit-return characteristic remains in effect. A transaction manager must set COMMIT-RETURN to either TX-COMMIT-COMPLETED or TX-COMMIT-DECISION-LOGGED.

  • Error

    When TXSETCOMMITRET fails to execute, it does not change the commit-return characteristic and returns one of the following negative values.

    Error Code Description

    [TX-EINVAL]

    COMMIT-RETURN is neither set to TX-COMMIT-COMPLETED nor TX-COMMIT-DECISION-LOGGED.

    [TX-PROTOCOL-ERROR]

    TXSETCOMMITRET was called in an inappropriate context. E.g., TXOPEN is not called yet.

  • Related Functions

    TXCOMMIT, TXOPEN, TXINFORM, TXGBEGIN, TXROLLBACK

2.20. TXSETTIMEOUT

The TXSETTIMEOUT function sets the transaction-timeout characteristic. The value specifies the period in which a transaction must complete before transaction timeout occurs. The period is the interval between a TXBEGIN call and a TXCOMMIT or TXROLLBACK call.

TXSETTIMEOUT can be called regardless of the mode its caller is in. If TXSETTIMEOUT is called in transaction mode, a new timeout value applies in the next transaction. The initial value of TRANSACTION-TIMEOUT is 0, which means that there is no time limit.

TRANSACTION-TIMEOUT specifies the maximum time allowed before a transaction timeout occurs (Unit: seconds). It can be set up to the maximum value of the S9(9) COMP-5 type, defined in an individual system.

  • Usage

    DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.
*
01 TX-INFO-AREA.
COPY TXINFDEF.

PROCEDURE DIVISION.
CALL "TXSETTIMEOUT" USING TX-INFO-AREA TX-RETURN-STATUS.

  • Return Value

    Result Description

    Success

    Returns a non-negative TX-OK.

    Failure

    Returns a negative error code. The existing transaction-timeout characteristic does not change.

  • Error

    When TXSETTIMEOUT fails to execute, TXSETTIMEOUT is set to one of the following values.

    Error Code Description

    [TX-EINVAL]

    Specified timeout value is invalid.

    [TX-PROTOCOL-ERROR]

    TXSETTIMEOUT was called in an inappropriate context. E.g., a caller still has not called tx-open().

    [TX-FAIL]

    A critical error occurred. A transaction manager can no longer handle jobs for an application. The reason for this error differs according to product characteristics.

  • Related Functions

    TXBEGIN, TXCOMMIT, TXOPEN, TXROLLBACK, TXINFORM

2.21. TXSETTRANCTL

The TXSETTIMEOUT function sets the transaction-control characteristic to a value in TRANSACTION-CONTROL. The setting determines whether to start a new transaction before TXCOMMIT and TXROLLBACK return to their caller. TXSETTRANCTL can be called regardless of the mode its caller is in. This setting remains in effect until changed by a subsequent call to TXSETTRANCTL.

  • Usage

    DATA DIVISION.
* Include TX definitions.
01 TX-RETURN-STATUS.
COPY TXSTATUS.
*
01 TX-INFO-AREA.
COPY TXINFDEF.

PROCEDURE DIVISION.
CALL "TXSETTRANCTL" USING TX-INFO-AREA TX-RETURN-STATUS.

    The following values can be set in TRANSACTION-CONTROL.

    Setting Value Description

    TX-UNCHAINED (default value)

    A new transaction is not started until TXCOMMIT and TXROLLBACK return to their caller. A caller must call TXBEGIN to start a new transaction.

    TX-CHAINED

    A new transaction is started before TXCOMMIT and TXROLLBACK return to their caller.

  • Return Value

    Result Description

    Success

    Returns a non-negative TX-OK.

    Failure

    Returns a negative error code. The existing transaction-control characteristic does not change.

  • Error

    When TXSETTRANCTL fails to execute, TXSETTRANCTL is set to one of the following values.

    Error Code Description

    [TX-EINVAL]

    Specified timeout value is invalid.

    [TX-PROTOCOL-ERROR]

    TXSETTRANCTL was called in an inappropriate context. E.g., a caller still has not called tx-open().

    [TX-FAIL]

    A critical error occurred. A transaction manager can no longer handle jobs for an application. The reason for this error differs according to product characteristics.

  • Related Functions

    TXBEGIN, TXCOMMIT, TXOPEN, TXROLLBACK, TXINFORM