SEND

For Web Services the SEND statement has the simple form shown here: it names a record which must have type SERVICE OUTPUT, it includes either CONTINUE or EXIT, and may include APPEND Each SEND writes data to the output message (in COBOL, PUT record [APPEND]), and if the SEND includes EXIT then the program is terminated.

APPEND

Without APPEND, SEND will overwrite any other data in the message, e.g. OJSAPP2 in the example above. With APPEND data should be added to any data that has already been sent, allowing logic such as that above where a number of occurrences of OJSAPP2 are written before the program terminates and sends the message.

APPEND is experimental, and it doesn’t currently work correctly with Micro Focus Enterprise Developer V6.0. However the generated COBOL code, which uses

006530 EXEC CICS JSAPP2

006540 PUT CONTAINER(JZContainerName) FROM(OJSAPP2) APPEND JSAPP2

006550 RESP(JZ-RESPONSE) JSAPP2

006560 END-EXEC. JSAPP2

Seems correct according to the IBM definition of PUT CONTAINER, and so this should work for IBM users. Until this is properly resolved, E-level message #662 is produced.

In a web service program, none of the other options for the SEND statement, which are designed for Classical CICS, may be used.

If you are not interested in Classical CICS, where messages are sent within CICS to 3270 screens and other programs, you do not need to read further.

Summary for Classical CICS Programs

Sends a message to CICS, to a screen, to another terminal, or to another program. For example

SEND CICS2S ALARM;

sends the screen CICS2S to a terminal, with an option set to cause the alarm to sound.

The general format of a SEND statement is

SEND [message-name] [Option]…

i.e. in the case above the message is named “CICS2S”, and the SEND statement includes the ALARM option.

Here are the more common options of the SEND statement. The full list will be given later.

Message Name

The message name, CICS2S in the example above, is the name of the message. If this is omitted, as in

SEND (CICS2.Region = custf2.region NORMAL);

then the message name is taken from the first item, e.g CICS2.

If a name is not given and there is no data list (for example, if the statement is simply

SEND;

then

a. If the first item is an unqualified name then the name given in the PROGRAM statement’s INSCREEN option is used

b. With web service programs using COMMAREA, the name of the COMMAREA. For example in this program

PROGRAM Web1 WEBSERVICE Mysvce COMMAREA Web1C;

…

SEND;

is equivalent to

SEND Web1C;

c. With web service programs using CONTAINER, the name of the output message. This is the program name prefixed with “O”, so that in this program

PROGRAM Web1 WEBSERVICE Mysvce CONTAINER JZWeb1;

…

SEND;

is equivalent to

SEND OWeb1;

Unless the message name is “text” it must be the name of a record layout already defined within the program, and will have been a screen created by the screen editor. The message name must follow the rules for external names, i.e. no longer than 8 characters, no hyphens, not a COBOL reserved word. See SEND TEXT below for the special rules that apply to this.

As with INSCREEN, if necessary Jazz will look for a definition in the copy library and include it. However, since you’ll probably need to set screen values before the SEND you’ll probably need to include (COPY) the screen layout into your program before it. If no such definition exists then you’ll have to create it.

The message name may be omitted if there are no other option. Thus in a program with

PROGRAM program-name INSCREEN(input-name) …,

SEND ;

is equivalent to

SEND input-name;

However

SEND ALARM;

is not, and requires the output screen to be named: -

SEND input-name ALARM;

Otherwise Jazz thinks that ALARM is a message name and gets confused.

The message name normally refers to a screen name or a web services message name, although it can refer to other definitions if the SEND statement also includes the PROGRAM option.

DATA

DATA lists [some of] the fields that will be sent. For example: -

SEND CICS2S DATA(REGION, NAME);

Normally you’ll omit the keyword DATA and write the data option directly after the screen name, e.g.

SEND CICS2S(REGION, NAME);

and of course as soon as you process the statement Jazz will qualify the field names: -

SEND CICS2S(CICS2S.Region, CICS2S.Name);

or: -

SEND (CICS2S.Region, CICS2S.Name);

All references must be to the same record: this would be invalid: -

SEND (Screen1.Region, Screen2.Name);

A reference to a field such as CICS2S.Region usually implies that a value is assigned from the related field CustF.Region to the screen field, CICS2S.Region, using the relationships that were built into the screen when you created it. You can use an assignment expression if you want data assigned from another field: -

SEND CICS2S(CICS2S.Region = Custf2.Region, CICS2S.Name = Custf2.Name);

You can refer to the whole screen, including a scrolling section, with a generic reference CICS2S.*. In this case you cannot use assignment expressions: all individual fields implied by the generic reference will use the built-in relationships.

See Data Field References below for more information. If the message is not a 3270 screen then there are no implied source fields, and each item will be assignment expressions, e.g.

SEND (MessageField = SourceField, …)

Program logic may have already moved some or all of the data to the output message. If the SEND also includes a data option, but does not include the ERASE option, then data already moved to the output message as well as the data named in the data option will be sent.

For 3270 screens, with each data item you can set options such as colours, highlighting, cursor position, etc. For example

SEND CICS2S(CICS2S.Region BRIGHT, CICS2S.Name CURSOR);

displays Region with double intensity, and sets the cursor to field Name. See Data Field Options below for more information.

ALARM

Synonym ERROR. Only valid when the output message is a 3270 screen.

This causes an alarm to sound when the screen is displayed.

ERASE

(Synonyms CLEAR, REFRESH)

This causes the screen to be cleared and sent, displaying it with its initial appearance as when CICS displayed the screen and invoked your program for the first time. With ERASE the screen layout including constants is sent, but all data positions are empty. Within your program this kind of SEND is usually written within logic like this: -

IF EIBAID = DFHCLEAR THEN

SEND CICS2S ERASE;

END IF;

CONTINUE

Normally your program will exit immediately after the SEND statement. To prevent this and continue with the following statement you can add CONTINUE to the SEND. See SEND and the Next Program

TRANSID and COMMAREA

TRANSID specifies the transaction id (4-character code) value used when your program exits immediately after the SEND statement. If TRANSID is specified then COMMAREA may also be specified, passing both a screen and data area to another program. The transaction code, screen, and commarea values must all be correct for the target program: thus if the target program begins: -

PROGRAM CICS4 CICS INSCREEN(CICS4S) COMMAREA(CICS4C) TRANSID (trn4) EXIT(Menu1);

then a valid SEND statement is

SEND CICS4S(CICS4S.*) TRANSID (trn4) COMMAREA(CICS4C);

However Jazz does not check that you have used the correct names:

SEND CICS4S(CICS4S.*) TRANSID (trn2) COMMAREA(CICS3C);

may be translated without any Jazz errors, but will result in MapFail or other CICS errors when you attempt to run the program.

SEND and the Next Program (3270 screens)

In a CICS application each program handling an input screen will start with a PROGRAM statement like this

*# Last Updated by IBMUSER at 16/12/2014 9:52:55 a.m.

PROGRAM CICS1 CICS INSCREEN(CICS1S) COMMAREA(CICS1C) TRANSID (trn1) EXIT(Menu1);

Program CICS1 is the ONLY program that uses INSCREEN(CICS1S) and TRANSID (trn1). There can be no other program naming CICS1S as its INSCREEN, or trn1 as its TRANSID. If program CICS1 is initiated with any other screen format there will be an error (type “Mapfail”) and the program will abort.

Within program CICS1 any SEND generated automatically by ACCEPT validation processing, and the SEND generated at the end of the main logic, send data back to this input screen. Thus the program terminates with

SEND CICS1S(CICS1S.*);

A program may send another screen. For example program CICS1 may contain

SEND CICS2S(CICS2S.*) TRANSID (trn2);

Obviously this screen cannot be sent to program CICS1 where it would cause a Mapfail error, so the SEND statement includes TRANSID to direct the output to another program.

Like sending to another screen, SEND TEXT also can’t return control to program CICS1 so the TRANSID option should be used there too. If neither CONTINUE nor TRANSID is given the SEND TEXT statement will unlock the keyboard and the user must enter a transaction code to direct what CICS should do next.

Jazz cannot check the association of TRANSID and program name. Thus if you write SEND CICS2S(CICS2S.*) TRANSID (trn1); the message will be directed to program CICS1, causing an error.

If CONTINUE is used instead of TRANSID then the execution path after the SEND should lead to an EXIT statement to direct where the response should be sent.

Data Field References (3270 screens)

When you define a screen to Jazz you can define fields by dragging them from your program’s data list. For example, here we have selected the field CICSCRC.Function ready to drag and drop this into an empty space on the screen CICSCRS: -

When we do so a set of screen fields is created - a caption, a data field, and an error indicator field - that match the field’s characteristics and the relationship between the external field and the field within the screen is recorded.

Because CICSCRC.Function is defined as a CHAR(1) field the data field in the screen takes a single character, marked by the blue X. With other fields a different format will be used: for example Region and District which were drag-and-dropped from SMALLINT fields have format ---9. We now have (at least) two fields in our program called “Function”, CICSCRC.Function and CICSCRS.Function, i.e. there is an external field, and a field within the screen. There may be other fields in our program sharing the name “Function”.

Except in SEND and ACCEPT statements a reference to a screen field like CICSCRS.Function is a normal reference like any other, and we could assign values to the screen fields, test their values, and so on. However we normally use ACCEPT and SEND to move the data to/from the external fields. Thus we’d write: -

ACCEPT (CICSCRS.Function, …)

and later

SEND CICSCRS (CICSCRS.Function, …)

With ACCEPT the value in the screen field CICSCRS.Function is first checked to see if it is valid according to the definition of the related external field CICSCRC.Function before it is assigned. SEND will assign the data from CICSCRC.Function to CICSCRS.Function, reformatting it if necessary.

SEND can be used without a data list. For example, SEND CICSCRS; will send the screen with the fields to which we have assigned value in preceding assignment or SET statements. If there is a data list plus prior assignments to screen fields then both assigned fields and fields named in the data list are transmitted.

Generic References, and Scrolling Sections

In both ACCEPT and SEND you can use generic references as a shorthand way of referring to many fields. Thus SEND CICS2S(CICS2S.*) will format and assign all the fields in the screen CICS2S.

A screen may contain a scrolling (paging) section, and this will be included in the display from SEND CICS2S(CICS2S.*). For example, screen CICS2S contains an area where up to 8 orders can be displayed. If the current customer has 8 or fewer orders they will all be displayed. If there are more that 8 orders then initially the first 8 will be displayed, and the user can page forward and back through the list with Page Down and Page Up (or PF8/PF7).

Data Field Options (3270 screens)

As noted above you can add attributes to references to control the appearance of the output screen. You can specify these attributes both with individual field references: -

SEND CICS2S(CICS2S.Region BRIGHT, CICS2S.Name CURSOR);

and with generic references: -

SEND CICS2S(CICS2S.* BRIGHT);

If applied to a generic reference then the attribute applies to all of the implied field references.

Data Field Options are as follows. You can choose one option from each group: if you use more than one, the later option is invalid and is rejected. Data options are: -

Cursor

Causes the cursor to be placed in this field. If several fields use the CURSOR option then the first (from the top of the screen) will receive the cursor, other CURSOR options will be ignored.

Protection attributes

PROT or UNPROT or SKIP

You can set PROT (means “Protected”) on an input field in circumstances when you want to prevent the user from entering data, and you can set a field to UNPROT to allow data entry. If neither is specified then the attributes defined with the screen will be used.

Note that you cannot set this attribute for a constant or output-only field: these are fixed as protected and not transmitted to/from your program.

Intensity attributes

NORMAL, BRIGHT, or DARK

Controls field display intensity.

BRIGHT displays the field with high intensity: you might use this to highlight errors, or emphasis particularly important fields.

DARK: the field is not shown. Use this for password fields, and to pass information to a screen and back that you don’t want the user to see (this can be a useful way of passing data from one part of a pseudo-conversation to another).

If none of these options are used then the attributes defined with the screen will be used.

SKIP

Causes the cursor to skip to the next field

MDT

Stands for “Modified Data Tag”. When a user types something into an input field then CICS sets an indicator, called a “Modified Data Tag”, showing that the data in this field has been modified. The system then knows that the data in this field is to be sent back from the 3270 terminal to the program. If the MDT is not set then there has been no change: CICS knows that there is no need to send the value back as the program already has its value.

Sometimes however you want to send data to a screen, and have it returned. This might be because the screen is initiating another program, or another part of the pseudo-conversation, and in spite of the apparent inefficiency of passing data to the terminal and reading it back again this can be a convenient way of managing your system logic. In such cases you should use the MDT option, so that CICS “thinks” that the data that you wrote into the field has been entered by a user and so will send it back to the program. MDT is often used together with DARK.

Highlighting Attributes

You can give one of these attributes to provide highlighting.

BLINK, REVERSE, UNDERSCORE

Colour

You can give one of these attributes

BLUE, RED, PINK, GREEN, TURQUOISE, YELLOW, NEUTRAL (or WHITE)

SEND TEXT (3270 screens)

This is a form of SEND that is useful for sending relatively unformatted messages. SEND TEXT is especially useful for debugging.

With SEND TEXT Jazz generates a data area from the SEND statement rather than using the screen editor, so you have relatively little control of the message’s appearance – you cannot use specific positioning, you cannot send a message and then await a reply, and you cannot use format options like colours, intensity, etc.

Here is an example of a SEND TEXT statement: -

SEND TEXT('Test SEND TEXT', Custf.Account, 123 NEWLINE,Custf.Name) DEBUG;

Like a normal SEND message( ) statement, the word TEXT is followed by a data list. The data list differs from the data list of a normal SEND statement in that: -

1. It may contain string or numeric constants. Examples above are 'Test SEND TEXT' and 123.

2. Fields may not be dimensioned. You may not refer to groups.

3. If you write options such as BRIGHT, BLINK, etc these options will be ignored. The only option that is relevant is NEWLINE. This means that there will be a new line following the item: thus the next item after 123, Custf.Name, will start on a new line.

4. If the statement option DEBUG is given then every field is preceded by its name, and followed by “;”

5. If ERASE is given then the screen will be cleared before this message. If ERASE is omitted then the message will overwrite text already on the screen up to the end of the message, leaving any further text displayed.

For example,

SEND text(cics3c.ts2start, cics3c.ts2Current-Record, jz.JZ-Index) DEBUG;

produced a display like this: -