PROGRAM

PROGRAM.. 1

Program-name. 1

General Options – BATCH/CICS, REPORT. 1

BATCH.. 1

CICS.. 1

REPORT. 2

Classical CICS Options. 2

INSCREEN(screen-name) 2

TRANSID(Transaction-id) 2

COMMAREA(Commarea-name) 3

EXIT(Program-name) 3

NOCLEAR.. 3

Web Service Options. 3

WEBSERVICE [ServiceName] 3

CONTAINER [ContainerName] 4

HTTP | HTTPS.. 4

REPLY ServiceName-OperationName. 4

 

The PROGRAM statement marks the start of a Jazz program, and describes its environment. You may have only one PROGRAM statement in a program, and it is normally the first statement in the program, although it may be preceded by one or more DEFINE statements. It may be stored in a Copy-book, in which case the COPY statement must be the first statement in the program.

 

Its format is: -

PROGRAM program-name [Option]…

for example

PROGRAM ShowMenu CICS;

Program-name

It must follow the rules for external names: i.e. be 8 characters or less, and not contain hyphens or special characters like “$”. It must be unique: it can not be the same as any other “Level 1 name” (Definition names etc).

General Options – BATCH/CICS, REPORT

BATCH

(default) This specifies that the program is to run as a batch program, being initiated by JCL and producing a report, copying a file, or sequentially updating a file. With BATCH your program can process physical-sequential files (types F, FB, V, VB, and U) as well as VSAM and SQL that can also be processed by CICS. The program cannot use CICS options like INSCREEN or SERVICE, nor statements like SEND and ACCEPT that deal with screens, nor INVOKE or REPLY.

CICS

Specifies that the program is an on-line program controlled by CICS. CICS is assumed if the PROGRAM statement contains any of the options implying a Classical CICS (3270-type screen) program – INSCREEN, TRANSID, EXIT, COMMAREA or NOCLEAR – or a web service – SERVICE, REPLY, CHANNEL or CONTAINER. 

 

If CICS is specified then the program may not use physical-sequential files (types F, FB, V, VB, and U), nor PRINT or REPORT statements.

REPORT

Specifies that the program has a report structure: a process loop reading an input file, using a control break structure invoking $Rpt-xxxx routines, and producing a report.  REPORT is currently used only for BATCH programs, but a future development will allow it to be used in web service programs also.

Classical CICS Options.

The following options are used if the program uses 3270 screens, and communicates through a COMMAREA (communications area).  They are invalid if BATCH is specified, and they conflict with Web Service Options.

INSCREEN(screen-name)

e.g. INSCREEN(Scrn1)

INSCREEN lets you specify that the program will be initiated by the system after the operator has responded to the screen named, and subsequent ACCEPT statements within the program may process data from the screen.

INSCREEN implies that the program is an on-line program, and so the CICS option is required. Jazz checks that the screen-name exists in the Jazz SCREENLIB;  if it does not, then you can invoke the screen editor to create the screen.

Click on INSCREEN and the record layout can be displayed as a normal DEFINE statement.  You should not edit this: if you want to make changes you should use the screen editor, accessed through the [Screen] button.

TRANSID(Transaction-id)

This specifies the transaction ID that will be used to initiate this program. Transaction ID’s must be 4 characters or less. The transaction-id is used: -

1.         If the screen template contains parameter value @TRN then this will be substituted by the transaction ID

2.         If the program terminates without specifying another transaction id, then this value is used. The program will be restarted when a response is received.

 

NOTE: the transaction ID defined to CICS, for example with the CEDA command, must correspond to the PROGRAM statement.  Jazz cannot check this.  If you wrote

            PROGRAM CICS1 TRANSID (TRNX) …

and then define to CICS
           
DEF TRANS(TRN1) PROGRAM(CICS1) GROUP(CICSG)

results will be incorrect.  You must either write TRANSID (TRN1) in the PROGRAM statement, or DEF TRANS(TRNX) in the CEDA command.

COMMAREA(Commarea-name)

Jazz always generates pseudo-conversational programs, so that when it SENDs a screen or exits in any other way the program is terminated. All data that is needed from one part of the program to another therefore has to be saved explicitly in a communication area. If you like you can think of COMMAREA as a kind of parameter. The Commarea name, like the screen name of the INSCREEN option, is a definition that must exist in the Jazz copy library.

 

Click on COMMAREA and the record layout is displayed, and can be edited.

 

COMMAREA may also be used with Web Service Programs.

EXIT(Program-name)

This specifies a program that is initiated when this program exits without SENDing a screen or through an explicit EXIT statement. Its main use is in specifying what is to happen on PF3/PF12 exit.

NOCLEAR

This option is only valid if the INSCREEN option is present.

 

With PROGRAM …. INSCREEN(screen) your program is going to start by reading the input screen, then deciding what to do with it. Jazz will automatically insert logic that will: -

·         Test that a message has been received with a length > 0

·         If a zero-length message has been received, send back an empty screen (displaying constants, but nothing in any of the data fields) with options so that this program will be re-started when the operator responds to it.

 

You usually want the same behaviour if the operator presses the Clear key, so Jazz creates logic as if you had written

IF EIBCALEN = 0 | EIBAID = DFHCLEAR  THEN

    SEND screen ERASE;

END IF;

 

If your PROGRAM statement includes NOCLEAR then the second part of the condition is omitted, and your program effectively contains

IF EIBCALEN = 0 THEN

    SEND screen ERASE;

END IF;

Web Service Options

The following options are used if the program provides a web service that may be invoked externally, or if it processes the reply to a web service.  If any of these options are used, then CICS is assumed.  They may not be used if BATCH is specified.  They conflict with Classical CICS Options except for COMMAREA.

WEBSERVICE [ServiceName]

Use this option when the program is to be invoked as a web service.  If no name is given, then “MySvce” is assumed, e.g.

            PROGRAM GetName WEBSERVICE;

is equivalent to

            PROGRAM GetName WEBSERVICE MySvce;

There may be several operations at this web service: this PROGRAM statement will refer to operation MySvce-GetName

 

The operation name (= program name) must be unique within the service, and the combination ServiceName-OperationName must be unique within your project.  The implication of this is that there is only one way of invoking program GetName, and that is as a service request to MySvce-GetName.

 

Right-click on WEBSERVICE and the record definitions for MySvce-GetName will be opened.  It can be edited.

CONTAINER [ContainerName]

Use this option if a web service provider communicates via a CHANNEL.  If omitted, the program communicates via COMMAREA.  Thus

          PROGRAM GetTime WEBSERVICE MySvce COMMAREA GetTimeC;

reads the web service input message from commarea, and the REPLY statement sends the output message using commarea also.  By comparison,

          PROGRAM GetTime WEBSERVICE MySvce CONTAINER CGetTime;

will read the input message from container CGetTime using the default channel, and will put the reply there also.

WSDL | JSON

WSDL causes Jazz to create a SOAP(Simple Object Access Protocol) message communicating with WSDL (Web Services Description Language).

 

JSON causes Jazz to create a REST (Representational State Transfer) message communicating with JSON (Javascript Object Notation).

 

Apart from this difference in the PROGRAM statement there should be no other differences within the Jazz program.

HTTP | HTTPS

Use HTTPS to have the DFHLS2WS step (generated into the job when the program is processed) specify a URI such as

            URI=https://192.86.32.59:9015/manajazz/gettim  

Otherwise this will include (for example)

            URI=http://192.86.32.59:9014/manajazz/gettim  

There is actually no difference in the COBOL, and you could change from one to the other if you were manually setting up your web service.

REPLY ServiceName-OperationName

This option isn’t yet implemented. Although it may parse and generate COBOL this has not been tested.

 

Use this option when the program is to be invoked to process the reply from some other web service. For example, the first SOATest program that we wrote invokes web service SOATest1 with: -

PROGRAM WST1 INSCREEN(WST1S) CICS TRANSID(TRW1);

DEFINE Wrk  DATA(

        Name VARCHAR (20),

        Result VARCHAR (70));

ACCEPT (WST1S.Name);

COPY SOATst-SOATest1 WEBSERVICE;

INVOKE SOATst-SOATest1(Wrk.Name) REPLY(Wrk.Result, Wrk.Name);

SEND WST1S(WST1S.Result);

This was a conversational program, with the advantages and disadvantages implied by this program structure.  We could have written this as a pair of programs to create a pseudo-conversational structure by terminating the program at the INVOKE, and writing a separate program to process the reply: -

PROGRAM WST1A INSCREEN(WST1S) CICS TRANSID(TRW1);

DEFINE Wrk  DATA(

        Name VARCHAR (20),

        Result VARCHAR (70));

ACCEPT (WST1S.Name);

COPY SOATst-SOATest1 WEBSERVICE;

INVOKE SOATst-SOATest1(Wrk.Name);

and separately

PROGRAM WST1B REPLY SOATst-SOATest1;

COPY WST1S;

          ACCEPT (WST1A.Result = $Reply.Result, WST1A.Name = $Reply.Name);

SEND WST1S;

 

Right-click on REPLY and the record definition for the web service reply can be viewed.  It should not be edited except from the program that created this service.