OSC Programming Features

This chapter describes OSC programming features for simplifying OSC application development.

1. Overview

In addition to the commands used to access OSC resources, EXEC CICS provides the following programming features to simplify OSC application development:

2. System Environment

System environment features allow access to the storage provided by OSC or to retrieve environment variable values that can be used to specify a structure or pointer.

This section explains a few data sharing methods. COMMAREA and TWA can be used to share data between programs, while CWA and TCTUA can be used between programs and other programs, or programs and transactions.

OSC Storage

In addition to local storage (the WORKING-STORAGE SECTION in the case of COBOL) for managing data accessed by business logic, OSC application programs can temporarily use OSC storage for application data. OSC storage helps to create interconnected applications by allowing data sharing between programs and transfer of execution results to another program or transaction.

  • Communication Area (COMMAREA)

    COMMAREA is used when sending and receiving data between two programs in a transaction or between two transactions executed from the same terminal.

    • Passing data between two programs in the same transaction

      A maximum of 32 KB of data can be transferred to a program by using the LINK or XCTL command. The DPL function uses the COMMAREA to transfer data between applications. The OTG and EXCI clients also use the COMMAREA to transfer data between client and server applications.

    • Passing data between two transactions executed from the same terminal

      A transaction can access data associated with the previous transaction with the RETURN command. This method is useful when writing a pseudo-conversational program.

      The user can use the ADDRESS command to get the address of the COMMAREA for data access. COBOL application programs can declare and use the DFHCOMMAREA field in the LINKAGE SECTION instead of using the ADDRESS command to access data.

  • Transaction Work Area (TWA)

    TWA is a data area allocated to each transaction by the system. This area is available while a transaction is being executed and is useful for managing a small amount of data in a transaction. It has the following characteristics.

    • The size of a TWA can be specified in the TWASIZE option of the TRANSACTION resource definition.

    • For each new transaction, the TWA is initialized to "0X00".

    • As in program areas such as WORKING-STORAGE SECTION, there is little user processing overhead.

    • No resource protection function is provided for the area.

  • Common Work Area (CWA)

    CWA is a data area allocated to each OSC application server. It is created when the OSC application server starts and remain available as long as the system is active. The CWA has the following characteristics.

    • The size of a CWA can be specified in the CWA_SIZE environment variable in the configuration file.

    • Unlike a TWA, it is not initialized to a specific value.

    • There is little user processing overhead.

    • No resource protection function is provided for the area.

    • No recovery function is provided for system failures.

    • All transactions can access it simultaneously.

      The user must manually perform tasks to protect the CWA. Since this area is accessible from a single node, its use is limited when multiple nodes are configured.

  • Terminal Control Table User Area (TCTUA)

    TCTUA is a user data area provided by a terminal. This area is shared by all transactions executed from that terminal. It has the following characteristics.

    • The size of a TCTUA can be specified in the USERAREALEN option of the TYPETERM resource definition.

    • It is not initialized to a specific value.

    • There is little user processing overhead.

    • Only the user of the terminal is allowed to access it.

    • No recovery function is provided for system failures.

System Environment Commands

There are several types of system environment commands: ADDRESS, a command that returns address values for OSC storage spaces; ADDRESS SET, a command that assigns address values; and those that return system environment setting values, such as ASSIGN and INQUIRE SYSTEM.

The following are descriptions of the system environment commands. For more information about each command, refer to the respective section.

Command Description

ADDRESS

Returns addresses of OSC storage spaces.

ADDRESS SET

Sets the address of a structure to a pointer value, or sets a pointer value to the address of a structure.

ASSIGN

Returns system environment variable values.

EXTRACT LOGONMSG

Accesses logon data from the server. The data is accessible only when the system initialization parameter LGNMSG is set to YES.

INQUIRE SYSTEM

Returns system setting values.

INQUIRE CONNECTION

Retrieves information about a local OSC region’s connection to another region or a remote system.

SET CONNECTION

Changes the attributes of an MRO or ISC.

2.1. ADDRESS

Returns the addresses of OSC storage spaces.

  • Syntax

    EXEC CICS ADDRESS [option …] END-EXEC.

  • Options

    Option Description

    COMMAREA

    Returns the COMMAREA address.

    CWA

    Returns the CWA address.

    EIB

    Returns the EIB address.

    TCTUA

    Returns the TCTUA address.

    TWA

    Returns the TWA address.

    Only parsing is supported for ACEE.

2.2. ADDRESS SET

Sets the address of a structure to a pointer value or set a pointer value to the address of a structure. The value returned by the USING option is stored with the SET option.

  • Syntax

    EXEC CICS ADDRESS SET [option …] END-EXEC.

  • Options

    Option Description

    SET

    Returns a pointer reference value.

    USING

    Specifies a pointer value.

2.3. ASSIGN

Returns system environment variable values.

  • Syntax

    EXEC CICS ASSIGN [option …] END-EXEC.

  • Options

    • ASSIGN command options

      Option Description

      ABCODE

      Returns the current ABCODE value. If an ABEND did not occur, this value will be filled with blank spaces.

      ABPROGRAM

      Returns the name of the program where ABEND occurred. If an ABEND did not occur, this value will be filled with blank spaces.

      ALTSCRNHT

      Returns the ROW value of the ALTRSCREEN attribute of the current terminal.

      ALTSCRNWD

      Returns the COLUMN value of the ALTRSCREEN attribute of the current terminal.

      APPLID

      Returns the APPLID value of server. An 8-character value that contains the name of the OSC server on which the current program is running.

      CHANNEL

      Returns the channel name of the current program.

      COLOR

      Returns the COLOR of a currently connected terminal.

      CWALENG

      Returns the length of the CWA area.

      DS3270

      Returns whether a currently connected terminal is a 3270 device.

      EXTDS

      Returns an indicator that shows whether the terminal accepts the 3270 extended data stream.

      FACILITY

      Returns the name of the terminal where the command was executed.

      FCI

      Returns a facility control indicator code. For example, X'01' is returned if the current transaction is executed in a terminal, and X'00' in the other cases.

      HILIGHT

      Returns the HIGHLIGHT of a currently connected terminal.

      INVOKINGPROG

      Returns the program name that executed a current program.

      KATAKANA

      Reports whether katakana is supported.

      NETNAME

      Returns the NETNAME of a currently connected terminal.

      OUTLINE

      Returns the OUTLINE of a currently connected terminal.

      OPID

      Returns the operator identification.

      PROGRAM

      Returns the name of a currently running program.

      PS

      Returns the PS of a currently connected terminal.

      QNAME

      Returns the name of the TDQ when a current transaction is executed by TDQ ATI.

      RESTART

      Returns an indicator that shows whether a task has been restarted or normally started.

      RESSEC

      Returns whether resource security is specified for a current transaction.

      SCRNHT

      Returns the height of the screen defined for the current transaction.

      SCRNWD

      Returns the width of the screen defined for the current transaction.

      SOSI

      Reports whether multi-byte (1-byte and 2-byte) character strings are supported.

      STARTCODE

      Returns a transaction request method.

      SYSID

      Returns the SYSID of the server. The value is specified to the VALUE of the SYSID key in the GENERAL section, from the osc.{servername} subject under OpenFrame Configuration. For more information, refer to OpenFrame Configuration.

      TCTUALENG

      Returns the length of the TCTUA area.

      TERMCODE

      Returns the code that combines the type and model number of a currently connected terminal.

      TWALENG

      Returns the length of a TWA area.

      USERID

      Returns the ID of the users currently logged in.

      USERNAME

      Returns the name of the users currently logged in.

      VALIDATION

      Returns the VALIDATION of a currently connected terminal.

      The following options are not supported: ABDUMP, APLKYBD, APLTEXT, ASRAINTRPT, ASRAKEY, ASRAPSW, ASRAREGS, ASRASPC, ASRASTG,BTRANS, CMDSEC, DEFSCRNHT, DEFSCRNWD, DELIMITER, DESTCOUNT, DESTID,DESTIDLENG, DSSCS, EWASUPP, GCHARS, GCODES, GMMI, INITPARM, INITPARMLEN, INPARTN, LANGINUSE, LDCMNEM, LDCNUM, MAPCOLUMN, MAPHEIGHT, MAPLINE, MAPWIDTH, MSRCONTROL, NATLANGINUSE, NEXTTRANSID, NUMTAB, OPCLASS, OPERKEYS, OPSECURITY, ORGABCODE, PAGENUM, PARTNPAGE, PARTNS, PARTNSET, PRINSYSID, RETURNPROG, SIGDATA, STATIONID, TASKPRIORITY, TELLERID, TERMPRIORITY, TEXTKYBD, TEXTPRINT, TRANPRIORITY, UNATTEND and USERPRIORITY.

    • STARTCODE options

      Option Description

      D

      Transaction is executed by a Distributed Program Link (DPL) request that does not specify the SYNCONRETURN option.

      DS

      Transaction is executed by a Distributed Program Link (DPL) request that specifies the SYNCONRETURN option.

      QD

      Transaction is executed by the TDQ trigger level.

      SD

      Transaction is executed by a START command with returned data.

      S

      Transaction is executed by a START command without returned data.

      TD

      Transaction is executed by a request from a terminal or a Tmax API such as tpcall, tpacall, or tpconnect.

2.4. EXTRACT LOGONMSG

Accesses the server’s logon data. The data are accessible only when the system initialization parameter LGNMSG is set to YES.

  • Syntax

    EXEC CICS EXTRACT LOGONMSG [option …] END-EXEC.

  • Options

    Option Description

    INTO

    Specifies the receiving field for the extracted data.

    SET

    Specifies the pointer reference to set to the address of the extracted data.

    LENGTH

    Specifies the length of the extracted data. If there is no data accessible, LENGTH is set to 0.

2.5. INQUIRE CONNECTION

Retrieves information about a local OSC region’s connection to another region or a remote system.

  • Syntax

    EXEC CICS INQUIRE CONNECTION [option …] END-EXEC.

  • Options

    Option Description

    ACCESSMETHOD

    Returns an indicator of the type of connection between the inquiry target and the local system.

    END

    Ends browsing.

    CONNECTION

    Specifies the four-character identifier of the remote system or region to inquire about.

    NETNAME

    Returns the eight-character name of the remote system from the NETNAME value specified in the CONNECTION definition.

    NEXT

    Repeats the INQUIRE command. Only one source definition is returned.

    PROTOCOL

    Returns the value of the protocol being used.

    START

    Starts browsing.

    The following options are not supported: ACQSTATUS, AUTOCONNECT, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSERID, CONNSTATUS, CONNTYPE, CQP, DEFINESOURCE, DEFINETIME, EXITTRACING, GRNAME, INSTALLAGENT, INSTALLTIME, INSTALLUSRID, LINKSYSTEM, MEMBERNAME, NQNAME, PENDSTATUS, RECEIVECOUNT, RECOVSTATUS, REMOTENAME, REMOTESYSNET, REMOTESYSTEM, SENDCOUNT, SERVSTATUS, XLNSTATUS and ZCPTRACING.

2.6. INQUIRE SYSTEM

Retrieves system setting values.

  • Syntax

    EXEC CICS INQUIRE SYSTEM [option …] END-EXEC.

  • Options

    Option Description

    DFLTUSER

    Returns the default user ID of the region. This value is specified to the VALUE of the DFLTUSER key in the SAF section, from the osc.{servername} subject under OpenFrame Configuration.

    GMMLENGTH

    Returns the length of the region server’s Good Morning text.

    GMMTEXT

    Returns the region’s Good Morning text. This value is specified to the VALUE of the GMTEXT key in the GENERAL section, from the osc.{servername} subject under OpenFrame Configuration.

    GMMTRANID

    Returns the region’s Good Morning transaction value. This value is specified to the VALUE of the GMTRAN key in the GENERAL section, from the osc.{servername} subject under OpenFrame Configuration.

    JOBNAME

    Returns the region’s JOBNAME value. This value is specified to the VALUE of the JOBNAME key in the GENERAL section, from the osc.{servername} subject under OpenFrame Configuration.

    SECURITYMGR

    Reports whether TACF is used or not.

    CICSSTATUS

    Returns the current execution status of OSC.

    SHUTSTATUS

    Returns a CVDA value indicating the shutdown of OSC.

For more information about the osc.{servername} subject, refer to OpenFrame Configuration Guide.

2.7. SET CONNECTION

Changes the attributes of an MRO or ISC.

  • Syntax

    EXEC CICS SET CONNECTION [option …] END-EXEC.

  • Options

    Option Description

    CONNECTION

    Specifies the four-character identifier of the remote system or region to configure.

    AFFINITY

    Indicates that the server is to end an affinity owned by OSC when it is a member of a generic resource group.

    1. The following options are not supported: ACQSTATUS, CONNSTATUS, EXITTRACING, PENDSTATUS, PURGETYPE, RECOVSTATUS, SERVSTATUS, UOWACTION and ZCPTRACING.

    2. Only parsing is supported for START, NEXT, and END.

3. Exception Condition Handling

After an EXEC CICS command is executed, execution results will be returned to the application program in the form of a RESP code. More information can be obtained about the execution results by examining the RESP and RESP2 codes or the RESP codes in the EIB. The OSC system allows to specify an alternate exception condition handling method by using these returned RESP codes. If an exception condition handling is not specified and an exception occurs, the default handling method for that exception is invoked.

The default actions taken by OSC are identical to those listed in the "IBM CICS Application Programming Reference" and "CICS System Programming Reference."
Exception Condition Handling Commands

The following is a list of commands that can be used to specify a new exception condition handling method. For more information about each command, refer to the respective section.

Command Description

HANDLE CONDITION

IGNORE CONDITION

Specifies how the system operates when a specific exception occurs in an application program.

POP HANDLE

PUSH HANDLE

Temporarily suspends and reinstates, respectively, the effects of handling commands to an application program.

When an exception occurs, the usual default action is ABEND. In some cases such as NOSPACE of WRITE TS, however, the default action may be to proceed and ignore the exception.

For more information about conditions where the exception is ignored, refer to IBM’s CICS documentation.

3.1. HANDLE CONDITION

Passes control of a command to a specified label when an exception condition occurs.

  • Syntax

    EXEC CICS HANDLE CONDITION [option …] END-EXEC.

  • Option

    Option Description

    condition

    Specifies the exception condition to be handled and the label where control will be passed in the event of an exception. If no label is specified, the default exception condition handling method will be followed.

    1. Timeout is supported only for parsing.

    2. The HANDLE CONDITION command must be executed before a command in which the specified exception condition could occur.

3.2. IGNORE CONDITION

Ignores the default action for specific exception conditions.

  • Syntax

    EXEC CICS IGNORE CONDITION [option …] END-EXEC.

  • Option

    Option Description

    condition

    Specifies the exception condition as option name.

3.3. POP HANDLE

Reinstates a HANDLE command that was previously the target of PUSH HANDLE. There are no particular options.

  • Syntax

    EXEC CICS POP HANDLE END-EXEC.

3.4. PUSH HANDLE

Suspends the current effect of HANDLE commands. There are no particular options.

  • Syntax

    EXEC CICS PUSH HANDLE END-EXEC.

4. ABEND Handling

ABEND (short for "ABnormal END") refers to the abnormal termination of a task. This can occur if a user enters the ABEND command, or if a task encounters an exception condition that causes it to terminate. If an ABEND occurs, any resources that can be recovered will be rolled back.

An ABEND can occur in the following cases:

  • User request through the ABEND command

  • Tmax service timeout

  • The default exception condition handling method of an EXEC CICS command may be 'ABEND'

This section describes the ABEND command as well as how to handle the ABEND situation.

ABEND Handling Commands

The following is a list of commands for ABEND. For more information about each command, refer to the respective section.

Command Description

ABEND

Requests an ABEND for the current task.

HANDLE ABEND

Specifies a label or a program to execute in the case of an ABEND.

4.1. ABEND

Requests an ABEND for the current task.

  • Syntax

    EXEC CICS ABEND [option …] END-EXEC.

  • Options

    Option Description

    ABCODE

    Specifies the ABEND code. If not specified, the ABEND code will be set to '????'.

    CANCEL

    Ignores the handling process specified by a HANDLE ABEND command.

    Only parsing is supported for NODUMP.

4.2. HANDLE ABEND

Specifies a label or program to be executed before exiting the program when an ABEND exception occurs. The handling method specified here is affected by the POP HANDLE and PUSH HANDLE commands.

If ABEND is specified at multiple program levels (called through the LINK command), OSC application server uses the nearest active HANDLE ABEND command starting from the logical level of the current application program and going up to higher levels.

  • Syntax

    EXEC CICS HANDLE ABEND [option …] END-EXEC.

  • Options

    Option Description

    CANCEL

    Cancels the previous ABEND setting.

    LABEL

    Specifies the label of the program that will receive control.

    PROGRAM

    Specifies the name of a program where control will be transferred to in the case of an ABEND.

    RESET

    Resets the canceled ABEND setting.

5. Resource Recovery

If an OSC application server or the OSC system is rebooted, or if a task ends abnormally, the resources that were being used must be recovered and returned to their prior states.

The default recovery point for resources is set just before the start of a task, but the recovery point can be changed by using the SYNCPOINT command. Programs are divided into logical sections based on recovery points; each divided section is called a Unit of Work (UOW) or Logical Unit of Work (LUW).

When the SYNCPOINT command is executed, all changes that were made in the previous UOW will be committed and a new UOW will be started. The SYNCPOINT ROLLBACK command rolls back any changes made to recoverable resources in the current UOW and then starts a new UOW.

If a program ends with the RETURN command, all changes made by the program will be committed automatically. If a program ends abnormally with the ABEND command or as the result of an exception, all recoverable resources will be rolled back.

Not all OSC system resources can be recovered. Those that can be recovered are as follows:

  • Files

  • Temporary Storage Queue (TSQ)

  • Transient data queues (TDQ)

  • DL/I Database

  • Requests made with the START command that specify the PROTECT option

File resources are recoverable by default. The TSQ and TDQ can be set to be recoverable in the resource definition configuration files. The DL/I database can be recovered as a feature of HiDB.

Resource Recovery Commands

The following commands can be used for resource recovery. For more information about each command, refer to the respective section.

Command Description

SYNCPOINT

Commits all changes made to recoverable resources since the previous SYNCPOINT.

SYNCPOINT ROLLBACK

Rolls back all changes made to recoverable resources since the previous SYNCPOINT.

5.1. SYNCPOINT

Commits all changes made to recoverable resources since the previous SYNCPOINT. Tasks are divided as UOW and there are no particular options for SYNCPOINT.

  • Syntax

    EXEC CICS SYNCPOINT END-EXEC.

5.2. SYNCPOINT ROLLBACK

Rolls back all changes made to recoverable resources since the previous SYNCPOINT. Tasks are divided as UOW and there are no particular options for SYNCPOINT ROLLBACK.

  • Syntax

    EXEC CICS SYNCPOINT ROLLBACK END-EXEC.

6. Built-in Functions

The OSC system provides the built-in functions DEEDIT and DIGEST. The DEEDIT function removes alphabetical and special characters from an EBCDIC data field, right aligns the remaining digits and pads the spaces to the left with zeros. The DIGEST function calculates the SHA-1 hash of a character string.

The following is a list of commands for the built-in functions. For more information about each function, refer to the respective section.

Command Description

BIF DEEDIT

Executes the DEEDIT function.

BIF DIGEST

Generates the SHA-1 hash.

6.1. BIF DEEDIT

Executes the DEEDIT function.

  • Syntax

    EXEC CICS BIF DEEDIT [option …] END-EXEC.

  • Options

    Option Description

    FIELD

    Specifies the name of the field to be edited.

    LENGTH

    Specifies the length of the field to be edited.

6.2. BIF DIGEST

Calculates a SHA-1 hash of a character string.

  • Syntax

    EXEC CICS BIF DIGEST [option …] END-EXEC.

  • Options

    Option Description

    BASE64

    Generates a 28-byte long result with BASE64 encoding.

    RECORD

    Specifies the character string to apply SHA-1 to.

    RECORDLEN

    Specifies the length of the character string.

    RESULT

    Returns the SHA-1 hash value in the BASE64 encoding format.

    Only parsing is supported for BINARY, DIGESTTYPE, and HEX.