Data Communication Features

This chapter describes data communication features for connecting OSC application programs with external terminals.

1. Overview

The following are data communication features that enable communication between OSC applications and external terminals. SPOOL supports integration with TJES.

2. Terminal Control

In the OSC system, client terminals are represented by TN3270 emulators. Using the TN3270 communications protocol, the TN3270 emulators send user input to the server and then display server responses on the terminal screen.

For a terminal to access an application server, terminal resource definitions must be configured on that server. Terminals that have been successfully configured can then send and receive data through an OSC 3270 gateway.

Terminal Control Commands

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

Command Description

CONVERSE

Sends data from an OSC application to a terminal, and receives data from a terminal.

FREE

Returns control of the terminal from an OSC application.

HANDLE AID

Passes control to a specified label when an AID (Attention Identifier) value is received through the terminal.

INQUIRE NETNAME

Retrieves the attributes from a terminal.

INQUIRE TERMINAL

Retrieves the attributes and status of a terminal.

ISSUE DISCONNECT

Terminates the connection between an OSC region and the terminal, and goes back to the initial screen of the OSC 3270 gateway.

ISSUE ERASEAUP

Deletes all unprotected fields of the 3270 buffer.

ISSUE PASS

Terminates the connection with the current OSC region, and connects to a specified OSC region.

ISSUE PRINT

Prints out the screen displayed on the terminal.

RECEIVE

Sends data from terminal to OSC application.

SEND

Sends data from OSC application to terminal.

SET TERMINAL

Modifies the attributes and status of a terminal.

2.1. CONVERSE

Sends and receives data from an OSC application to a 3270 terminal, and receives data from the terminal.

  • Syntax

    EXEC CICS CONVERSE [option …] END-EXEC.

  • Options

    Option Description

    CONVID

    Identifies a conversation associated with the command by a 4-character name.

    DEFAULT

    Uses the DEFAULT screen size.

    FROM

    Specifies the data area containing the data to be sent to terminal.

    FROMLENGTH|FROMFLENGTH

    Specifies the size of the data to be sent.

    INTO

    Specifies the data area where received data will be stored.

    MAXLENGTH|MAXFLENGTH

    Specifies the maximum length of the data to be received.

    NOTRUNCATE

    Indicates that if the data received from the terminal is larger than the buffer size, that data will be temporarily stored and then retrieved by the next RECEIVE command.

    SESSION

    Specifies a 1-4 character symbolic identifier of a session TCTTE.

    SET

    Specifies a pointer reference that will contain the address of the data received from the terminal.

    STATE

    Returns the stats of a transaction program.

    TOLENGTH|TOFLENGTH

    Specifies the size of the received data.

    Only parsing is supported for ALTERNATE, ASIS, ATTACHID, CTLCHAR, DEFRESP, DEST, DEFRESP, ERASE, FMH, FROMDCC, LEAVEKB, LINEADDR, LDC, PSEUDOBIN, STRFIELD, and TODCC.

2.2. FREE

Returns control of a terminal from an OSC application.

  • Syntax

    EXEC CICS FREE END-EXEC.

  • Options

    Option Description

    CONVID

    Specifies a 4-character name that identifies a session to release.

    SESSION

    Specifies a 1- 4 character symbolic identifier of a session TCTTE.

    STATE

    Returns the status of the currently running conversation.

2.3. HANDLE AID

Passes control to a specific label when an attention identifier (AID) is received by a terminal. The HANDLE AID command is covered by the POP|PUSH HANDLE commands.

  • Syntax

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

  • Options

    Option Description

    ANYKEY

    Handles any of the <PA> and <PF> keys as well as the <CLEAR> key.

    CLEAR

    Handles the <CLEAR> key.

    CLRPARTN

    Handles the <CLRPARTN> key.

    ENTER

    Handles the <ENTER> key.

    LIGHTPEN

    Handles a light-pen AID.

    OPERID

    Handles an AID from an operator identity card reader, magnetic slot reader (MSR), or extended MSR.

    PA1-PA3

    Handles the <PA1> through <PA3> program access keys.

    PF1-PF24

    Handles the <PF1> through <PF24> program function keys.

    TRIGGER

    Handles a trigger field AID.

2.4. ISSUE DISCONNECT

Terminates the connection between an OSC application server and a terminal.

  • Syntax

    EXEC CICS ISSUE DISCONNECT END-EXEC.

Only parsing is supported for SESSION.

2.5. ISSUE ERASEAUP

Deletes all unprotected fields of the 3270 buffer.

  • Syntax

    EXEC CICS ISSUE ERASEAUP END-EXEC.

Only parsing is supported for WAIT.

2.6. INQUIRE NETNAME

Returns the attributes of a terminal.

  • Syntax

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

  • Options

    Option Description

    ACQSTATUS

    Indicates whether the terminal is connected.

    AIDCOUNT

    Returns a fullword binary value that represents the number of AIDs queued at the terminal. If there are no AIDs, 0 is returned.

    ALTSUFFIX

    Indicates the suffix of a MAPSET name when converting a map.

    ATISTATUS

    Indicates whether a terminal is available for Automatic Transaction Initiation (ATI).

    CREATESESS

    Indicates whether a terminal is set to connect to a region when ATI is executed for the terminal (only connecting to VTAM) while not being connected to a region.

    NETNAME

    Returns an 8-character network name of the terminal.

    SERVSTATUS

    Indicates whether a terminal is available.

    SIGNONSTATUS

    Indicates whether there is a user who signed into a terminal.

    TASKID

    Returns a fullword binary value that indicates the user task being executed at the terminal. If no task is being executed at the terminal, 0 is returned.

    TERMINAL

    Specifies the NETNAME of a target terminal.

    TERMSTATUS

    Indicates whether a terminal is connected.

    TTISTATUS

    Indicates whether a transaction can be executed in a terminal.

    Only parsing is supported for REMOTENAME and TRANSACTION.

2.7. INQUIRE TERMINAL

Returns the attributes and status of a terminal.

  • Syntax

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

  • Options

    Option Description

    ALTPRINTER

    Returns a 4-character name of a printer specified here if the printer specified in the PRINTER option is unavailable.

    END

    Ends browsing.

    NETNAME

    Specifies the name of a terminal.

    NEXT

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

    NEXTTRANSID

    Displays the name of the transaction to run next.

    PRINTER

    Returns a 4-character name of the default printer. If this printer is not available, the system uses the one specified in the ALTPRINTER option.

    OPERID

    Returns a 3-character operator identification code of the user who has logged in at a terminal.

    START

    Starts browsing.

    SERVSTATUS

    Displays whether the terminal is available.

    TERMINAL

    Specifies a 4-character name of the terminal or session to inquire about.

    USERID

    Returns the ID of the user of a terminal or a session. If there is no user who has logged in, the system returns the default user ID.

    UCTRANST

    Returns the CVDA value which determines whether to convert data entered in a terminal to all uppercase.

    1. The following options are not supported: AIDCOUNT, ACQSTATUS, ALTPRTCOPYST, ALTSUFFIX, ATISTATUS, AUDALARMST, BACKTRANSST, COLORST, DEVICE, FROMFEEDST, HILIGHTST, KATAKANAST, LIGHTPENST, OUTLINEST, PAGESTATUS, PROGSYMBOLST, PRTCOPYST, REMOTENAME, REMOTESYSTEM, SIGNONSTATUS, SOSIST, TASKID, TERMSTATUS, TERMPRIORITY, TERMMODEL,TRANSACTION, TTISTATUS, USERAREA, USERAREALEN, USERNAME, VALIDATIONST.

    2. CREATESESS and SESSIONTYPE are not supported options, but are supported for parsing.

2.8. ISSUE PASS

Terminates current connection to a OSC region and makes new connection to a specified OSC region.

  • Syntax

    EXEC CICS ISSUE PASS [options ...] END-EXEC.

  • Options

    Option Description

    LUNAME

    Specifies the name of a OSC region to connect.

    FROM

    Specifies the data area that is to be passed to the connected OSC region.

    LENGTH

    Specifies the length of the data issued.

Only parsing is supported for LOGMODE, LOGONLOGMODE, and NOQUIESCE.

2.9. ISSUE PRINT

Prints out the screen displayed on the terminal. There are no options.

  • Syntax

    EXEC CICS ISSUE PRINT END-EXEC.

2.10. RECEIVE

Allows an application program to receive data from a 3270 terminal.

  • Syntax

    EXEC CICS RECEIVE [option …] END-EXEC.

  • Options

    Option Description

    ASIS

    Does not convert lowercase to uppercase in the 3270 stream.

    BUFFER

    Specifies a 3270 buffer to be read.

    CONVID

    Identifies a conversation associated with the command by a 4-character name.

    INTO

    Specifies the data area where received data will be stored.

    LENGTH|FLENGTH

    Specifies the size of the received data. If the INTO option is specified and MAXLENGTH or MAXFLENGTH are not specified, this option specifies the maximum size of buffer to be received. If the SET option is specified, the size of the received data is returned.

    MAXLENGTH|MAXFLENGTH

    Specifies the maximum length of the data to be received.

    NOTRUNCATE

    Indicates that if the data received from the terminal is larger than the buffer size, that data will be temporarily stored and then retrieved by the next RECEIVE command.

    SESSION

    Specifies the 1-4 character symbolic identifier of a session TCTTE.

    SET

    Specifies the pointer reference that contains the address of the data to receive from the terminal.

    STATE

    Returns the state of the current conversation.

    Only parsing is supported for DCC, LEAVEKB, PASSBK, and PSEUDOBIN.

2.11. SEND

Sends data from an OSC application to a terminal.

  • Syntax

    EXEC CICS SEND [option …] END-EXEC.

  • Options

    Option Description

    ALTERNATE

    Uses the ALTERNATE screen size.

    CONFIRM

    Indicates that an application using a conversation that is sync level 1 or 2 requires confirmation from a remote application program.

    CTLCHAR

    Specifies the Write Control Character (WCC).

    CONVID

    Identifies a conversation associated with the command by a 4-character name.

    DEFAULT

    Uses the DEFAULT screen size.

    ERASE

    Clears the existing terminal screen.

    FROM

    Specifies the data area containing the data to be sent to terminal.

    LAST

    Indicates that this transmission is the last transmission of transaction.

    LENGTH|FLENGTH

    Specifies the size of the data to be sent.

    SESSION

    Specifies the 1-4 character symbolic identifier of a session TCTTE.

    STATE

    Returns the state of the current conversation.

    STRFIELD

    Indicates that the structure field is contained in the data specified in the FROM option.

    WAIT

    Returns the control to the application after processing the command. In OSC, the control is returned after processing the command regardless of this option.

    1. The following options are not supported: ASIS, CBUFF, CNOTCOMPL, DCC, DEFRESP, FMH, INVITE, LEAVEKB, PASSBK, and PSEUDOBIN.

    2. Only parsing is supported for ATTACHID, DEST, LDC, and LINEADDR.

2.12. SET TERMINAL

Modifies some attributes and status of a terminal. Currently, only the RELEASE option is supported.

  • Syntax

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

  • Options

    Option Description

    ACQUIRED

    Makes connection to a specified terminal.

    ALTPRTCOPY

    Uses the hardware COPY feature to satisfy a print request from the alternative printer.

    ALTPRINTER

    Specifies the name of a 3270 printer, up to 4 characters, to use as an alternative to the printer defined in the PRINTER option.

    ATI

    Makes ATI available.

    AUTOPAGEABLE

    Automatically writes pages following the first page to the terminal.

    CANCEL

    Cancels AIDs queueing for the specified terminal. AIDs waiting in the local OSC system are cancelled. However, AIDs with an associated task that have already begun are not cancelled.

    COLDACQ

    Makes connection to a specified terminal that does not need resynchronization.

    CREATE

    Creates connection to a terminal, if there is none, when ATI is executed.

    DISCREQ

    Accepts a disconnection request and executes the CLSDST macro command to terminate a session with a specified LU.

    EXITTRACE

    Enables tracing of exit activity.

    FORCE

    Same as FORCEPURGE.

    FORCEPURGE

    Purges a transaction immediately.

    INSERVICE

    Makes the specified terminal available for use.

    KILL

    Terminates a task without ensuring system and data integrity. Use this option if the PURGE and FORCEPURGE options fail.

    NOALTPRTCOPY

    Disables the hardware COPY feature.

    NOATI

    Makes ATI unavailable.

    NOCREATE

    Does not create connection if a terminal is not connected when ATI is executed.

    NODISCREQ

    Does not accept a disconnection request.

    NOEXITTRACE

    Disables tracing of exit activity.

    NOOBFORMAT

    Indicates that outboard formatting is not supported.

    NOPRTCOPY

    Disables the hardware COPY feature.

    NORELREQ

    Does not release a logical unit when there is a request from another communication server application program.

    NOTTI

    Indicates that the terminal cannot initiate transactions.

    NOUCTRAN

    Indicates that uppercase translation for the transaction at the terminal will not be performed.

    NOZCPTRACE

    Disables ZCP tracing.

    OBFORMAT

    Indicates that outboard formatting is supported.

    OUTSERVICE

    Makes a specified terminal unavailable for use.

    PAGEABLE

    Writes pages following the first page to the terminal at the operator’s request.

    PRINTER

    Specifies the name of the default printer in response to a print request. The name can be up to four characters.

    PRTCOPY

    Enables the hardware COPY feature for the default printer to satisfy a print request.

    PURGE

    Terminates a transaction only where system and data integrity can be ensured.

    RELEASED

    Releases the specified terminal.

    RELREQ

    Releases a LU when it is executing a transaction.

    SPECTRACE

    Enables special tracing.

    STANTRACE

    Enables standard tracing.

    TERMINAL

    Specifies the 4-character name of a terminal.

    TRANIDONLY

    Performs uppercase translation of the transaction ID of the terminal.

    TTI

    Indicates that the terminal can initiate transactions.

    UCTRAN

    Performs uppercase translation of the terminal input.

    UCTRANST

    Option to convert terminal input to uppercase letters.

    Options are:

    • UCTRAN

    • NOUCTRAN

    • TRANIDONLY

    ZCPTRACE

    Enables ZCP tracing.

    1. The following options are not supported: ACQSTATUS, ALTPRTCOPYST , ATISTATUS, CREATESESS, DISCREQST, EXITTRACING, MAPNAME, MAPSETNAME, NEXTTRANSID, OBFORMATST, OPERID, PAGESTATUS, PRTCOPYST, PURGETYPE, RELREQST, SERVSTATUS, TCAMCONTROL, TERMSTATUS, TERMPRIORITY, TRACING, TTISTATUS, UCTRANST and ZCPTRACING.

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

3. Mapping Support

Mapping Support is a programming interface that enables communication between OSC programs and TN3270 terminals.

Data is transferred to and from TN3270 terminals through the 3270 data stream, a data structure. OSC application programs, however, use different structures. Mapping support converts 3270 data streams received from terminals to a data format supported by an OSC application program, and vice versa.

Mapping support has the following benefits:

  • It eliminates terminal dependencies from the OSC application program. This makes it unnecessary for application developers to learn the complicated 3270 stream structure and to implement the program logic for data control in an application. Instead, they can control terminal input and output with a handful of relatively simple EXEC CICS commands.

  • It separates screen design and format from application logic. To change the design and format of an application screen, you only need to change the map file. To change the program logic, you only needs to change the program source code. This is possible because the map file and the program source code are independent, which allows you to write new programs using the existing screen design and format and to maintain the existing maps and programs.

For more information about mapping support functions, refer to OpenFrame OSC Mapping Support Guide.
Mapping Support Commands and Functions

The commands and functions related to Mapping Support are classified as follows. For more information about each command, refer to the respective section.

  • Map transmission/reception

    Command Description

    RECEIVE MAP

    Receives screen input from a terminal.

    SEND MAP

    Sends screen information to a terminal.

    SEND PAGE

    Completes and sends a configuration of logical messages that are created using the ACCUM option of SEND MAP or SEND TEXT.

  • Text transmission

    Command Description

    SEND TEXT

    Sends only text data to a terminal.

    SEND TEXT NOEDIT

    Sends the user data to a terminal without converting to BMS files.

  • Terminal control

    Command Description

    SEND CONTROL

    Controls a terminal.

  • Data transmission between terminals

    Command Description

    ROUTE

    Defines the target terminal to send logical messages to. The logical messages are created using the ACCUM option of SEND MAP or SEND TEXT.

  • Paging function

    Command Description

    CSPG

    Outputs logical messages, created by the ACCUM option of SEND MAP or SEND TEXT, into pages.

3.1. CSPG

Outputs logical messages, created by the ACCUM option of SEND MAP or SEND TEXT, into pages.

Use the PAGING option when creating a logical message by using the ACCUM option of SEND MAP or SEND TEXT in a user program. After creating a logical message, calling SEND PAGE calls CSPG transaction.

  • Configuration

    Specify the following resources in the system definition resource.

    DEFINE PROGRAM(DFHCSPG) GROUP(group name)
DEFINE TRANSACTION(CSPG) GROUP(group name) PROGRAM(DFHCSPG) TWASIZE(255) RESSEC(YES)

    Add the CSPG setting to the VALUE of the SKRPF{NN} key in the CSPG section, from the osc.{servername} subject under OpenFrame Configuration. The setting format is 'CSPG (command) (option). Specify a shortcut key to 'SKRPF{NN}'. (for example, SKRPF21, SKRPF22)

    The following configures CSPG.

    ================================================================================
    SUBJECT     |     SECTION     |        KEY        |          VALUE
================================================================================
  osc.OSCOIVP1  |       CSPG      |      SKRPF21      |      CSPG getpage F
                |                 |      SKRPF22      |      CSPG getpage P
                |                 |      SKRPF23      |      CSPG getpage N
                |                 |      SKRPF24      |      CSPG getpage L
================================================================================

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

  • Commands

    Command Description

    GETPAGE

    Reads the specific page of the logical message.

    MSGTERM

    Deletes the logical message.

    MESSCHN

    Concatenates multiple logical messages.

    MSGCOPY

    Copies the logical message into another terminal.

    Only GETPAGE and MSGTERM commands are supported.

  • Options

    • GETPAGE

      Option Description

      F

      Reads the first page.

      P

      Reads the previous page.

      N

      Reads the next page.

      L

      Reads the last page.

    • MSGTERM

      Option Description

      B

      Deletes the logical message displayed in the current terminal.

3.2. RECEIVE MAP

Allows an application program to receive screen data from a terminal. If the FROM option is used, the data to be mapped will be received from the specified buffer instead of a terminal.

  • Syntax

    EXEC CICS RECEIVE MAP [option …] END-EXEC.

  • Options

    Option Description

    ASIS

    Indicates that lowercase letters in a 3270 input data stream are not translated into uppercase letters.

    FROM

    Specifies a data area containing data to be mapped.

    INTO

    Specifies a COBOL variable declaration part to be sent to a terminal.

    LENGTH

    Specifies the length of the data to read.

    MAP

    Specifies the name of a map to be displayed.

    MAPSET

    Specifies the name of a MAPSET that contains a map.

    SET

    Returns the address of read data.

    Only parsing is supported for INPARTN and TERMINAL.

3.3. ROUTE

Defines the target terminal to send logical messages to. The logical messages are created using the ACCUM option of SEND MAP or SEND TEXT.

  • Syntax

    EXEC CICS ROUTE [option …] END-EXEC.

  • Options

    Option Description

    LIST

    Defines the terminal and other routing options.

3.4. SEND CONTROL

Controls a terminal.

  • Syntax

    EXEC CICS SEND CONTROL [option …] END-EXEC.

  • Options

    Option Description

    ACCUM

    Creates a logical message.

    ALARM

    Specifies alarm settings.

    ALTERNATE

    Clears the screen area corresponding to the ALTERNATE screen size, when used with the ERASE option.

    CURSOR

    Specifies the location of the cursor on the terminal screen. This value must be between 0 and 1919. As an example, if 0 is specified, the cursor will be located at (row, col) (1,1). If 80 is specified, the cursor will be located at (2,1).

    DEFAULT

    Indicates that the terminal uses the DEFAULT screen size.

    ERASE

    Clears the screen before new data is displayed at the terminal.

    ERASEUP

    Clears data from the input field.

    FORMFEED

    Inserts a FORMFEED character to the very beginning of the 3270 stream.

    FREEKB

    Unlocks the keyboard after data is written.

    FRSET

    Resets all fields.

    LAST

    Indicates that this output is the last output for a transaction. Available only for logical units.

    PRINT

    Sends the screen data to a print device, not a terminal.

    PAGING

    Indicates that the output data is not immediately displayed at the terminal but placed in temporary storage and displayed by an administrator’s paging command.

    TERMINAL

    Sends the screen data to a terminal. (Default value)

    WAIT

    Returns the control to the application after processing the command. In OSC, the control is returned after processing the command regardless of this option.

    Only parsing is supported for ACTPARTN, LDC, MSR, OUTPARTN, L40, L64, L80, REQID, and SET.

3.5. SEND MAP

Allows an application program to send mapped data to a terminal.

  • Syntax

    EXEC CICS SEND MAP [option …] END-EXEC.

  • Options

    Option Description

    ACCUM

    Creates logical messages.

    ALARM

    Specifies alarm settings.

    ALTERNATE

    Clears the screen area corresponding to the ALTERNATE screen size, when used with the ERASE option.

    CURSOR

    Specifies the location of the cursor on the terminal screen. This value must be between 0 and 1919. As an example, if 0 is specified, the cursor will be located at (row, col) (1,1). If 80 is specified, the cursor will be located at (2,1).

    DATAONLY

    Indicates that only application program data will be written to the terminal screen.

    DEFAULT

    Indicates that the terminal uses the DEFAULT screen size.

    ERASE

    Clears the screen before new data is displayed at the terminal.

    ERASEAUP

    Clears data from the input field.

    FORMFEED

    Inserts a FORMFEED character to the very beginning of the 3270 stream.

    FREEKB

    Unlocks the keyboard after data is written.

    FROM

    Specifies the data area containing the data to be sent to terminal.

    FRSET

    Resets all fields.

    LAST

    Indicates that this output is the last output for a transaction. Available only for logical units.

    LENGTH

    Specifies the length of data to send with the FROM option.

    MAP

    Specifies the name of the map to be sent to a terminal.

    MAPSET

    Specifies the name of the MAPSET that contains the map.

    MAPONLY

    Indicates that only the default map data will be written to the terminal screen.

    SET

    Specifies the pointer to be set to the address of the input data.

    PAGING

    Indicates that the output data is not to be immediately sent to the terminal but to be placed in temporary storage and displayed at the operator’s paging command.

    PRINT

    Sends the screen data to a print device, not a terminal.

    TERMINAL

    Sends the screen data to a terminal. (Default value)

    WAIT

    Returns the control to the application after processing the command. In OSC, the control is returned after processing the command regardless of this option.

    Only parsing is supported for ACTPARTN, MSR, FMHPARM, HONEOM, OUTPARTN, LDC, L40, L64, L80, NOFLUSH, NLEOM, and REQID.

3.6. SEND PAGE

Completes configuring a logical message created by the ACCUM option on SEND MAP or SEND TEXT.

  • Syntax

    EXEC CICS SEND PAGE [option …] END-EXEC.

  • Options

    Option Description

    SET

    Specifies the pointer to be set to the address of the input data.

    RELEASE

    Returns the control to the system after executing the SEND PAGE command.

    RETAIN

    Controls paging screens after executing the SEND PAGE command and then returns the control to an application.

3.7. SEND TEXT

Sends only text data to a terminal.

  • Syntax

    EXEC CICS SEND TEXT [option …] END-EXEC.

  • Options

    Option Description

    ACCUM

    Creates logical messages.

    ALARM

    Specifies alarm settings.

    ALTERNATE

    Clears the screen area corresponding to the ALTERNATE screen size, when used with the ERASE option.

    CURSOR

    Specifies the location of the cursor on the terminal screen. This value must be between 0 and 1919. As an example, if 0 is specified, the cursor will be located at (row, col) (1,1). If 80 is specified, the cursor will be located at (2,1).

    DEFAULT

    Indicates that the terminal uses the DEFAULT screen size.

    ERASE

    Clears the screen before new data is displayed at the terminal.

    FORMFEED

    Inserts a FORMFEED character to the very beginning of the 3270 stream.

    FREEKB

    Unlocks the keyboard after data is written.

    FROM

    Specifies the data area containing the data to be sent to the terminal.

    JUSFRIST

    Places text data at the top of a page.

    JUSLAST

    Places text data at the bottom of a page.

    LAST

    Indicates that this output is the last output for a transaction. Available only for logical units.

    LENGTH

    Specifies the length of data to send with the FROM option.

    PAGING

    Indicates that the output data is not immediately displayed at the terminal but placed in temporary storage and displayed by an administrator’s paging command.

    PRINT

    Sends the screen data to a print device, not a terminal.

    SET

    Specifies the pointer to be set to the address of the input data.

    TERMINAL

    Sends the screen data to a terminal. (Default value)

    WAIT

    Returns the control to the application after processing the command. In OSC, the control is returned after processing the command regardless of this option.

    Only parsing is supported for ACCUM, ACTPARTN, FMHPARM, HEADER, HONEOM, JUSTIFY, OUTPARTN, L40, L64, L80, LDC, MSR, NLEOM, PAGING, REQID and TRAILER.

3.8. SEND TEXT NOEDIT

Sends non-map text data to the terminal. The basic operation is the same as the SEND TEXT command, but it does not allow screen editing by the user (ACCUM/HEADER/TRAILER, etc.) and outputs only text.

  • Syntax

    EXEC CICS SEND TEXT NOEDIT [option …] END-EXEC.

  • Options

    Option Description

    ALARM

    Specifies alarm settings.

    DEFAULT

    Indicates that the terminal uses the DEFAULT screen size.

    ERASE

    Clears the screen before new data is displayed at the terminal.

    FREEKB

    Unlocks the keyboard after data is written.

    FROM

    Specifies the data area containing the data to be sent to the terminal.

    LAST

    Indicates that this output is the last output for a transaction. Available only for logical units.

    LENGTH

    Specifies the length of data to send with the FROM option.

    PAGING

    Indicates that the output data is not to be immediately sent to the terminal but to be placed in temporary storage and displayed at the operator’s paging command.

    PRINT

    Sends the screen data to a print device, not a terminal.

    TERMINAL

    Sends the screen data to a terminal. (Default value)

    WAIT

    Returns control to the application after processing the command. Regardless of the option, OSC will only return control if command processing is terminated.

4. SPOOL File Access

The OSC application server provides an interface to allow user programs to use spool resources in the TJES system. The interface is used by the batch system to manage the data stored in TJES SPOOL or used by TJES to run batch jobs. The data written to a spool file is placed in the same directory specified to the VALUE of the JOBID key in the GENERAL section, from the osc.{servername} subject in OpenFrame Configuration, under the system spool directory.

Spool File Access Commands

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

Command Description

SPOOLCLOSE

Closes a spool file.

SPOOLOPEN OUTPUT

Opens and configures a spool file.

SPOOLWRITE

Writes data to a spool file.

4.1. SPOOLCLOSE

Closes a spool file. A spool file can be closed manually or automatically when a task ends. When a spool file is closed, a spool processing request is sent to TJES.

  • Syntax

    EXEC CICS SPOOLCLOSE [option …] END-EXEC.

  • Options

    Option Description

    KEEP|DELETE

    KEEP sends a spool file to the target node. DELETE deletes a spool file.

    TOKEN

    Specifies the token value of a spool file to close.

4.2. SPOOLOPEN OUTPUT

Opens and configures a spool file.

  • Syntax

    EXEC CICS SPOOLOPEN OUTPUT [option …] END-EXEC.

  • Options

    Option Description

    CLASS

    Specifies the class.

    NODE

    Specifies the ID of the node that will be used to route the spool file.

    NOCC|ASA|MCC

    Specifies the carriage-control character to use when printing.

    OUTDESCR

    Specifies a pointer reference variable to be set to the address of the field containing the address of a string of parameters to the OUTPUT statement of JCL.

    PRINT|PUNCH|RECORDLENGTH

    Specifies the length of the record to write.

    USERID

    Specifies the ID of the user that will process the spool file.

    TOKEN

    Specifies the value of the spool file token.

    To write data to the internal reader, set the USERID to INTRDR in the SPOOLOPEN OUTPUT command. If /*EOF is written in the last record appended to the spool file, the file will be sent to the TJES internal reader when the file is closed.

4.3. SPOOLWRITE

Writes data to a spool file. If data is sent with the token value received when the spool file was opened will be written to the specified spool file. Multiple SPOOLWRITE operations can be executed on one spool file.

  • Syntax

    EXEC CICS SPOOLWRITE [option …] END-EXEC.

  • Options

    Option Description

    FROM

    Specifies the data area containing the data to be written.

    FLENGTH

    Specifies the length of data to be written.

    LINE|PAGE

    Indicates the data format.

    TOKEN

    Specifies the spool token used to identify the file to which to write.

5. Console Output

Provides an interface with which user programs can print data to the console. Data is printed to the tconmgr screen and the console log available in the OpenFrame system.

For more information about functions of tconmgr, refer to OpenFrame Tool Reference Guide.
Console Display Command

The following is the console display command. For more information about the command, refer to the respective section.

Command Description

WRITE OPERATOR

Displays a message in an operator console.

5.1. WRITE OPERATOR

Sends a message to an operator console, tconmgr, in the OpenFrame system. The REPLY option is supported to wait for a reply.

  • Syntax

    EXEC CICS WRITE OPERATOR [option …] END-EXEC.

  • Options

    Option Description

    ACTION

    Specifies an action code associated with the message.

    CRITICAL

    Indicates that the message requires a final action by the operator and that the message is critical and will remain on the screen until the operator deletes it.

    MAXLENGTH

    Specifies the length of the data area set in the REPLY option in the range of 1-119 bytes. This option is required if the REPLY option is specified.

    NUMROUTES

    Specifies a fullword binary value that represents the number of routing codes.

    REPLY

    Specifies the area of data to receive a reply from the operator. Using this option suspends the transaction. To resume it, provide the REPLY input by using tconmgr or the [Console] menu from [Base] in OpenFrame Manager.

    REPLYLENGTH

    Specifies the length of the operator’s reply that has been received.

    TEXT

    Specifies the message to be sent to the console.

    TEXTLENGTH

    Specifies the length of the text. If tspecified, the length is 0-121 bytes. If not specified, the length is 0-690 bytes.

    TIMEOUT

    Specifies a fullword binary value that represents the maximum duration of time for the server to wait before returning control to the transaction.

    1. Only parsing is supported for EVENTUAL, IMMEDIATE, and ROUTECODES.

    2. For more information about the [Console] from [Base] in OpenFrame Manager, refer to OpenFrame Manager User Guide.

6. Web Service Communication

The OSC application server provides an interface through which a client program can communicate with an external system using web services. That is, the OSC application server serves as a requester that uses a web service protocol to make request for a service to an external provider.

Web Service Communication Command

The following is the web service communication command. For more information about the command, refer to the respective section.

Command Description

INVOKE WEBSERVICE

Requests a service to a web service provider.

6.1. INVOKE WEBSERVICE

Requests a service to a web service provider. A web service request is processed by Tmax Java Gateway or AnyLink in OpenFrame.

  • Syntax

    EXEC CICS INVOKE WEBSERVICE [option …] END-EXEC.

  • Options

    Option Description

    CHANNEL

    Specifies the name of a channel that contains the request data. This channel will also contain the response data.

    OPERATION

    Specifies the name of an operation to perform.

    URI

    Specifies the URI of a web service.

    WEBSERVICE

    Specifies the name of the web service resource that has defined a web service.

    For more information about AnyLink and Tmax Java Gateway, refer to the respective manual.

7. HTTP Communication

OSC provides an interface to operate as an HTTP server or client through the HTTP protocol. If an HTTP server receives a request from an external client, it processes the requested transaction and returns the result to the client. An HTTP client sends a request to an external HTTP server and receives a response from the server. When OSC operates as an HTTP server, it receives a request sent from an external client through WAS’s oschttp servlet.

For more information about how to deploy WAS to use the oschttp servlet, refer to the WAS product manual.
HTTP Communication Commands and Programs

The following is a list of HTTP communication commands and programs. For more information about each command, refer to the respective section.

Command and Program Description

DFHWBA

Used when OSC operates as an HTTP server.

EXTRACT TCPIP

Obtains information about TCP/IP of the current transaction when OSC operates as an HTTP server.

WEB CONVERSE

Sends a request to an external server and receives a response from the server when OSC operates as an HTTP client.

WEB CLOSE

Closes the connection with an external server when OSC operates as an HTTP client.

WEB ENDBROWSE FORMFIELD

Ends browsing the FORM field of HTML requested by an external client when OSC operates as an HTTP server.

WEB EXTRACT

Obtains information about a request from an external client, when OSC operates as an HTTP server.

WEB OPEN

Opens a connection with an external server when OSC operates as an HTTP server.

WEB RECEIVE

Receives an external client’s request and saves the HTTP payload when OSC operates as an HTTP server.

WEB READNEXT FORMFIELD

Reads the name and value of the next FORM in the FORM field of HTML requested by an external client when OSC operates as an HTTP server.

WEB READ HTTPHEADER

Extracts the HTTP header information received from the external server when OSC operates as an HTTP server.

WEB SEND

Sends a response to an external client’s request when OSC operates as an HTTP server.

WEB STARTBROWSE FORMFIELD

Starts browsing the FORM field of HTML requested by an external client and specifies the first position of the FORM field, when OSC operates as an HTTP server.

WEB WRITE HTTPHEADER

Creates HTTP header information to be sent to an external server when OSC operates as an HTTP server.

7.1. DFHWBA

DFHWBA is a program used when OSC operates as an HTTP server.

When a client request arrives at OSC through the oschttp servlet on WAS, the DFHWBA program is called. The program checks URIMAP and TCPIPSERVICE resources in SD and calls a client’s desired program. First, it is checked whether there is URIMAP that matches PATH of the URIMAP resource and there is an analyzer. If there is an analyzer, a program to execute with the analyzer is specified and executed. If there is no analyzer, the TCPIPSERVICE resource that matches the used PORT is searched for and then a program to execute with the analyzer set as URM of TCPIPSERVICE is specified and executed.

  • Configuration

    The following resources must be defined in the system definition resource.

    DEFINE PROGRAM(DFHWBA) GROUP(DFHGRP) LANGUAGE(C)
DEFINE TRANSACTION(Alias Transaction Name) GROUP(DFHGRP) PROGRAM(DFHWBA) TWASIZE(255)

Currently, DFHWBADX and DFHWBAAX are supported as analyzers.

7.2. EXTRACT TCPIP

Obtains information about TCP/IP of the current transaction when OSC operates as an HTTP server.

  • Syntax

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

  • Options

    Option Description

    CLIENTADDR

    Returns the IP address of the client that sent a HTTP request to OSC.

    CADDRLENGTH

    Returns the length of the IP address of the client that sent a HTTP request to OSC.

7.3. WEB CONVERSE

Sends a request to an external server and receives a response from the server when OSC operates as an HTTP client.

  • Syntax

    EXEC CICS WEB CONVERSE [option …] END-EXEC.

  • Options

    Option Description

    FROM

    Data to send.

    FROMLENGTH

    Data size to send.

    INTO

    Storage space to save a received response.

    MAXLENGTH

    Maximum storage space size to save a received response.

    MEDIATYPE

    MEDIATYPE of data to send.

    METHOD

    METHOD of the request to send.

    QUERYSTRING

    QUERYSTRING in URL.

    QUERYSTRLEN

    QUERYSTRING size.

    SESSTOKEN

    Token connected through WEB OPEN.

    TOLENGTH

    Response size.

    URIMAP

    Name of the URIMAP resource that defines the external server.

    PATH

    Path to a specific resource within the server that the application needs to access.

    PATHLENGTH

    Length of PATH.

    CLOSESTATUS

    Specifies whether the HTTP header’s Connection option is set to close or keep-alive.

    BASICAUTH

    Specifies that the current session requires HTTP basic authentication.

    USERNAME

    ID of users who are allowed access. If the USERNAME option is used, the PASSWORD option must also be used.

    USERNAMELEN

    Length of the buffer provided in the USERNAME option.

    PASSWORD

    Password corresponding to the user ID to which access is allowed.

    PASSWORDLEN

    Length of the buffer provided in the PASSWORD option.

    STATUSCODE

    Data area to receive the HTTP status code sent by the server.

    STATUSTEXT

    Data area to receive the text returned by the server to describe the HTTP status code.

    STATUSLEN

    Length of data area to receive in STATUSTEXT option.

    Currently, GET, HEAD, POST, PUT, TRACE, OPTIONS, and DELETE are supported for METHOD.

7.4. WEB CLOSE

Closes the connection with an external server when OSC operates as an HTTP client.

  • Syntax

    EXEC CICS WEB CLOSE [option …] END-EXEC.

  • Options

    Option Description

    SESSTOKEN

    Token used to connect to the external server.

7.5. WEB ENDBROWSE FORMFIELD

Ends browsing the FORM field of HTML requested by an external client when OSC operates as an HTTP server. The WEB STARTBROWSE FORMFIELD command must be executed prior to this command.

  • Syntax

    EXEC CICS WEB ENDBROWSE FORMFIELD END-EXEC.

7.6. WEB EXTRACT

Obtains information about the most recent HTTP request written to the OSC by an external client and allocated to the application for processing when the OSC acts as an HTTP server.

  • Syntax

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

  • Options

    Option Description

    HOST

    Data area to receive the host of the URL for HTTP requests.

    HOSTLENGTH

    Length of the buffer provided in the HOST option.

    HTTPMETHOD

    HTTP method string.

    METHODLENGTH

    Length of buffer provided in HTTPMETHOD option.

    HTTPVERSION

    Data area to contain the HTTP version for the web client.

    VERSIONLEN

    Length of the buffer provided in the HTTPVERSION option.

    PATH

    Data area to receive the PATH of the URL for HTTP requests.

    PATHLENGTH

    Length of the buffer provided in the PATH option.

    QUERYSTRING

    Data area to receive QUERYSTRING of URL for HTTP request.

    QUERYSTRLEN

    Length of the buffer provided in the QUERYSTRING option.

    REQUESTTYPE

    Received request type.

Currently, the command is supported only when the OSC is the server.

7.7. WEB OPEN

Opens a connection with an external server when OSC operates as an HTTP server.

  • Syntax

    EXEC CICS WEB OPEN [option …] END-EXEC.

  • Options

    Option Description

    SESSTOKEN

    Token used to open a connection.

    URIMAP

    Name of the URIMAP resource that defines the server for HTTP communication.

    HOST

    Hostname of the server for HTTP communication.

    HOSTLENGTH

    Size of the host name of the server for HTTP communication.

    PORTNUMBER

    Server port number for HTTP communication.

    SCHEME

    Protocols with or without SSL.

7.8. WEB READ HTTPHEADER

Extracts the HTTP header information of the external server when OSC operates as an HTTP client.

  • Syntax

    EXEC CICS READ HTTPHEADER [option …] END-EXEC.

  • Options

    Option Description

    HTTPHEADER

    Name of HTTP header to extract.

    NAMELENGTH

    Length of HTTP header name.

    SESSTOKEN

    Token used to open a connection.

    VALUE

    Buffer to store the extracted HTTP header value.

    VALUELENGTH

    Length of the buffer provided in the VALUE option.

Currently, the command is supported only when OSC is the client.

7.9. WEB READNEXT FORMFIELD

Reads the name and value of the next FORM in the FORM field of HTML requested by an external client when OSC operates as an HTTP server. The WEB STARTBROWSE FORMFIELD command must be executed prior to this command.

  • Syntax

    EXEC CICS WEB READNEXT FORMFIELD [option …] END-EXEC.

  • Options

    Option Description

    FORMFIELD

    Storage space for the name of the HTML FORM.

    NAMELENGTH

    Length of the name of the HTML FORM.

    VALUE

    Storage space to save the value corresponding to the name of the HTML FORM.

    VALUELENGTH

    Length of the value corresponding to the name of the HTML FORM.

7.10. WEB RECEIVE

Receives an external client’s request and saves the HTTP payload when OSC operates as an HTTP server.

  • Syntax

    EXEC CICS WEB RECEIVE [option …] END-EXEC.

  • Options

    Option Description

    CLNTCODEPAGE

    CODEPAGE of CLIENT.

    HOSTCODEPAGE

    CODEPAGE of HOST.

    INTO

    Storage space to save the HTTP payload.

    LENGTH

    Length of the HTTP payload.

    MAXLENGTH

    Maximum size of the storage space set in INTO.

    Since OSC uses ASCII for data communication, CLNTCODEPAGE and HOSTCODEPAGE are meaningless.

7.11. WEB SEND

Sends a response to an external client’s request when OSC operates as an HTTP server.

  • Syntax

    EXEC CICS WEB SEND [option …] END-EXEC.

  • Options

    Option Description

    DOCTOKEN

    Token used to send DOCUMENT as a response.

    CLNTCODEPAGE

    CODEPAGE of DOCUMENT.

    Since OSC uses ASCII for data communication, CLNTCODEPAGE is meaningless.

7.12. WEB STARTBROWSE FORMFIELD

Starts browsing the FORM field of HTML requested by an external client and specifies the first position of the FORM field, when OSC operates as an HTTP server.

  • Syntax

    EXEC CICS WEB STARTBROWSE FORMFIELD [option …] END-EXEC.

7.13. WEB WRITE HTTPHEADER

Enters HTTP header information to send a request to an external server when OSC operates as an HTTP client.

  • Syntax

    EXEC CICS WRITE HTTPHEADER [option …] END-EXEC.

  • Options

    Option Description

    HTTPHEADER

    Name of HTTP header to extract.

    NAMELENGTH

    Length of HTTP header name.

    SESSTOKEN

    Token used to open a connection.

    VALUE

    Value of the HTTP header specified in the HTTPHEADER option.

    VALUELENGTH

    Length of HTTP header value

Currently, the command is supported only when the OSC is the client.