The ACCEPT Statement

The ACCEPT statement validates and moves data, normally from an input message or 3270-type input screen.

 

The ACCEPT Statement 1

Statement Format 1

Introductory Background. 1

Situation 1 – Using ACCEPT with Local Data. 1

Situation 2:  Getting data from a 3270-type screen. 2

Situation 3:  Getting Data from a Web Service Message. 3

Statement Options. 4

FROM (record name) 4

DATA.. 5

EXCEPT (Data list) 6

TOLIKE.. 7

SETMDT. 7

ACCEPTNULLS.. 7

CONTINUE or EXIT. 8

UPDATE.. 9

MESSAGE (field name) | NOMESSAGE.. 9

ACCEPT Validation Logic. 9

Statement Format

            ACCEPT [FROM(record name)] [DATA](data list) [EXCEPT(data list)]

                        [TOLIKE]

                        [SETMDT]

                        {[CONTINUE] | [EXIT]} [UPDATE] [MESSAGE(field name) | NOMESSAGE]

                        [ACCEPTNULLS]

Introductory Background

This section gives you a quick introduction to the ACCEPT statement and the way that it might be used, in preparation for the more formal and complete language rules starting at Statement Options.

Situation 1 – Using ACCEPT with Local Data.

A normal assignment statement like

            Wrk.A = Wrk.B;

moves data from B to A.  So does

            ACCEPT (Wrk.A = Wrk.B) MESSAGE(Wrk.Message);

Now imagine that we’ve defined the fields: -

DEFINE Wrk DATA(

    A CHAR(2) CODES(AK:Alaska,AL:Alabama,AR:Arkansas,

    WI:Wisconsin,WV:'West Virginia',WY:Wyoming) [US-States]

    B CHAR(2),

    Message CHAR(40));

 

The assignment statement Wrk.A = Wrk.B; moves the data as efficiently as possible, but does not check that the data is valid.  If Wrk.B is not a valid US State Code then Wrk.A will receive an invalid value but there will be no warning and only when A is displayed as “*********” (perhaps by another program) will the error be detected.

 

In contrast, ACCEPT (Wrk.A = Wrk.B); checks that the value is valid:if it is not then the error is detected.  You can test for this with

            IF $Error = True THEN;

and (with appropriate options) error messages will be set for display.  You should always use ACCEPT when you cannot be sure whether the data is valid, particularly when you’re processing input messages from Web Services or Screens.

Situation 2:  Getting data from a 3270-type screen

ACCEPT is particularly powerful when used with input messages from Web Services Messages or 3270 screens.  Suppose that we have created a 3270-type screen such as CICS2S by dragging fields known to the program into the screen: -

 

Here is the first part of our program: -

PROGRAM CICS2 CICS INSCREEN(CICS2S) TRANSID(TRN2) COMMAREA(CICS2C) EXIT(menu1);

ACCEPT (CICS2S.Function);

 

The field CICS2S.Function was dragged on to the screen from CICS2C, where it is defined: -

COPY custf;

DEFINE CICS2C COMMAREA DATA(

    Function CHAR(1) CODES (E:Enquiry,U:Update,A:Add,D:Delete) VALUE 'E',

    SAVE LIKE custf.*,

    JZ-XCTL LIKE Jazz.Flag); 

 

When ACCEPT refers to input from a 3270 screen: -

1.                  The screen definition has recorded the relationship between CICS2S.Function and CICS2C.Function.  You don’t need to write

ACCEPT (CICS2C.Function = CICS2S.Function);

      you simply name the screen field, and the name of the other field is implied.

2.                  Fields in the screen are defined with a terminating field that can be set to “*” if there is an error.  Also there is a field called “Error” which can carry a longer message.  For example, notice the “*” after Region, and the message on the 2nd-to-last line: -

3.                  If any errors are found then the program will be terminated and control returned to the user for correction, unless the CONTINUE option is used.

Situation 3:  Getting Data from a Web Service Message

With a 3270 screen the relationship between the input field and a corresponding program field is built into the screen definition, and the Jazz screen editor creates a standard field called “Error” for messages such as “Region: not numeric”.  This doesn’t apply to a web service message, so you have to give ACCEPT some help, telling it where to assign data, and perhaps where to put error messages.

Where to assign data

One way of telling ACCEPT where the data goes it to use assignment-form items.   For individual fields: =

ACCEPT (Wk2.f2 = InputMessage.F2);

and for several fields

ACCEPT (Custf.* = InputMessage.*);

           

Another is to use TOLIKE, which is useful when the web service message is defined using LIKE.  For example, with an input message defined: -

DEFINE IWSPG3 SERVICE DATA([Input message

    Function CHAR(1) CODES(E:Enquiry,U:Update,A:Add,D:Delete) VALUE Enquiry,

    JZ-Custf-Skip SMALLINT VALUE 0,

    Custf GROUP,

        Account LIKE CustF.Account,

        Region LIKE CustF.Region,

        District LIKE CustF.District,

        END GROUP,

    ViewState GROUP, [Must not be changed

        CheckSum-Custf CHAR(40),

        END GROUP);

 

            ACCEPT (IWSPG2.Region,IWSPG2.District,) TOLIKE;

is equivalent to

            ACCEPT (Custf.Region = IWSPG2.Region, Custf.District = IWSPG2.District,);

 

Refer to TOLIKE below.

Error reporting

If there is no MESSAGE option Jazz will look for a field named “Error”.  The normal search rules for an unqualified field mean that this will usually be the field defined in the INSCREEN or CONTAINER definition.   If it can’t find any such field then NOMESSAGE is assumed.

 

With this background: -

Statement Options

FROM (record name)

This option identifies the input record from which data is examined for validity and assigned if valid. If omitted, the input record is determined as follows: -

1.         For classical CICS programs in which INSCREEN identifies a 3270 input screen, the input record name is the INSCREEN name. For example in the ACCEPT statement in

PROGRAM MENU1 CICS INSCREEN(MENU1S);

ACCEPT ();

FROM(MENU1S) is assumed.

2.         For Web Service provider programs the default input record name is the input record defined by the service.  Thus with

PROGRAM GetTime WEBSERVICE MySvc COMMAREA(GetTimeC);

ACCEPT ();

FROM(GetTimeC) is assumed.

With.

PROGRAM GetTime WEBSERVICE MySvc CONTAINER(GetTimeContainer);

FROM(IGetTime) is assumed.

 

If no FROM option is present and no value is implied (i.e. the PROGRAM statement has neither INSCREEN nor WEBSERVICE options), then the FROM option value is taken from the first assignment. 

 

If present, the FROM option must precede the DATA option.   Normally statement options may be given in any order: this is one of the rare exceptions to this general syntax rule.  The reason for this exception is so that then unqualified references in DATA can be correctly qualified.

DATA

The keyword “DATA” is normally omitted, and the data list is written immediately after the statement keyword ACCEPT.  Thus you’d write

          ACCEPT (MENU1S.Function);

rather than its equivalent,

            ACCEPT INPUT MENU1S DATA (MENU1S.Function);

 

You may name one or several items, each item being separated by a comma or OR from the following item. If the record is a 3270 screen, then the correspondence between input fields and target fields is pre-specified and items may be single field references, generic references, or assignment statements.  For other types items must be assignment statements unless the statement contains the TOLIKE option. 

 

For example,

          ACCEPT (CICS2S.*);

          ACCEPT (CICS2S.Function, CICS2S.Region, Wrk.Month = CICS2S.Billingcycle);

 

For the assignment form, the target field must exist outside the INPUT record, while the source field must exist within it.  The source field must be an INPUT or INOUT field: for 3270 fields this is determined individually when the screen was created, for web service COMMAREA messages the INPUT or INOUT properties may be specified within the definition, while for container messages the input and output records are separately defined.   The target field determines the validation rules.

OR

Normally items in the data list are separated by commas: ACCEPT (F1, F2, ….);   However you can separate them by OR, like this: -

ACCEPT (CICS4S.Function, CICS4S.Keyfield OR CICS4S.Name);

OR, which is especially designed to handle multiple keys (KEY, DKEY, and UKEY options) suppresses the normal required-field check, but checks that at least one of the fields is present.  Key fields, and other fields defined as REQUIRED, must be entered, and if they are not then the ACCEPT’s validation logic will produce a message “field:Value Absent”.  By default both Keyfield and Name are required (because they’re keys), but in their use as alternate keys the user will probably enter one or the other.  Without OR the user would have to put a value into both.

 

OR and Default Values

When OR is used the ACCEPT statement will cause the target fields to be initialised if they are not given a value. For example, with

ACCEPT (CICS4S.Function, CICS4S.Account OR CICS4S.Name);

the fields that are related to CICS4S.Account and CICS4S.Name, (for example CustF.Account and Custf.Name) are set to their initial value at the start of the ACCEPT logic. Thus if no value for CICS4S.Account is entered the value of CustF.Account will remain as zero.  (This is essential to make a following statement like

GET custf KEY(CustF.Account OR CustF.Name);

 work correctly)

Generic References

A generic reference in an ACCEPT statement means “All the input fields for which the corresponding fields exist”.  Constant and output-only fields will be ignored, as will fields that don’t have corresponding fields defined within this program.  For Classical CICS (3270) programs you’ll write single references, like

          ACCEPT (CICS2S.*);

With web services you’ll write generic assignment statements such as

            ACCEPT (CustF.* = IWSPG3.Custf.*);

With either form you can use EXCEPT to exclude some fields from the ACCEPT logic.

EXCEPT (Data list)

This is used with a generic reference to exclude some of the fields that might otherwise be changed.  For example, imagine that you were writing a program updating orders for a customer.   Customer records are in file Custf, orders are in file Orders.  Orders.OrdNbr is the primary key of the Orders record, and Orders.OrdCustid is a duplicate key, and will have the value of Custf.Account to be related to the current customer.

 

You might write something like this: -

*   Process a selected child record.  Generated logic is a basic update

ACCEPT (Orders.OrdNbr);

GET orders  KEY(Orders.OrdNbr) UPDATE CHECKSUM IWSPG4.CheckSum-orders;

    ACCEPT (Orders.* = IWSPG4.orders.*) MESSAGE OWSPG4.ERROR;

END GET orders UPDATE RESPOND OWSPG4;

Of course you mustn’t update either Orders.OrdNbr or Orders.OrdCustid.  No problem if you had written individual data items, you’d just omit them from the data list, but with the generic assignment it is likely that the input record contains these fields, in which case they might be changed.  To exclude them from the generic reference we write

ACCEPT (Orders.* = IWSPG4.orders.*) EXCEPT(OrdNbr, ORDCustid) MESSAGE OWSPG4.ERROR;

Writing unqualified EXCEPT references, as here, will result in their being resolved, hopefully to the source or target record.  If they’re resolved to another record then change the reference to refer to either the source (IWSPG4) or target (Orders) records, otherwise they’ll be ignored.

          ACCEPT (Orders.* = IWSPG4.orders.*) EXCEPT(Orders.OrdNbr, Orders.ORDCustid)

TOLIKE

This option is invalid if the FROM record, either inferred or specified, is INSCREEN.  In a 3270 screen the relationship between the input fields and other program fields is defined by the screen generation process.

 

TOLIKE uses the LIKE relationship in the definition to create the same effect.  This is useful when the input fields are LIKE fields in several different records, but errors result when they are defined LIKE a type of data that can’t accept an assignment – for example SYSTEM, CONSTANT, and other reference-only types.  

 

When the ACCEPT contains TOLIKE but the data item is written as an assignment, then the assignment target is used.

 

If the ACCEPT item has neither explicit nor inferred target then it validates the data, but doesn’t assign it to another field.

SETMDT

This option is only valid when ACCEPT is used with 3270 input data. 

 

If present then, if the ACCEPT finds one or more data errors, then the Modified Data Tag is set for all fields named in the data list.  This has the effect of ensuring that valid data that has been already entered does not need to be re-entered as the system will automatically treat these fields as “modified” and return them to the program on the next response when the operator corrects the errors. This is particularly useful when data is being added.  Imagine that the user enters values for all 6 fields, but makes an error with field E: -

            ACCEPT (A, B, C, D, E, F);

The system responds, displaying the values of all 6 fields and an error message.  The user corrects field E and clicks [Enter].  Only field E is returned with the message, and there may be errors because values were missing for the other fields.  However, with

            ACCEPT (A, B, C, D, E, F) SETMDT;

the previously entered values are re-sent along with the correction for E.

CONTINUE | EXIT

Logic resulting from

          ACCEPT (CUSTNQY.Account) EXIT;

is: -

·         Check that CUSTNQY.Account is valid for assignment to the corresponding field CUSTF.Account;

·         IF it is valid *, then copy the value from CUSTNQY.Account into CUSTF.Account, converting it from the CHAR format of the screen to whatever format CUSTF.Account requires

·         ELSE Set error messages, redisplay the screen, and exit from the program

 

*           Invalid values MAY be assigned.  If a field passes initial checks (something present, numeric if required) then it is assigned to the target field before remaining checks such as RANGE are done.  See below.

 

Thus with this logic statements following the ACCEPT won’t be executed.

 

On the other hand,

          ACCEPT (CUSTNQY.Account) CONTINUE;

does not exit from the program, but instead execution continues with the next Jazz statement.

 

Usually neither CONTINUE or EXIT is specified.  Jazz determines the default according to the Error Message Field.  See MESSAGE (field name) I NOMESSAGE below for details, but in summary, the ACCEPT statement may name this field with

          ACCEPT (data) MESSAGE ErrorField;

or use option NOMESSAGE.  If either of these options are given then Jazz looks for a field called “Error”. If ErrorField can’t be found, then there will be an error message, and Jazz will continue as if NOMESSAGE was specified.

 

·         If there is no Error Message Field, or ErrorField is in a record whose type is neither SCREEN nor SERVICE, then CONTINUE is assumed. Thus in situation 1 where ACCEPT is used with internal data: -

            ACCEPT (Wrk.A = Wrk.B);

Jazz assumes CONTINUE.

·          Where ErrorField is in a definition that has type SCREEN or SERVICE then EXIT will be assumed.

UPDATE

If this option is present then an error message will be produced if none of the fields in the ACCEPT list have been changed in the screen named by INSCREEN.  For example: -

   WHEN (Update, Add);

        GET custf WHERE(CustF.Account=CICS2C.Save.Account) UPDATE CHECKCOPY(CICS2C.SAVE);

        ACCEPT (CICS2S.Region,CICS2S.District,CICS2S.Name,CICS2S.SalesThisMonth,

            CICS2S.SalesYTD,CICS2S.Billingcycle,CICS2S.DateCommenced) UPDATE;

        UPDATE custf;

        CICS2S.error = 'Update/Addition successful. Get next record or exit';

        CICS2C.Function = Enquiry;

 

If none of the screen fields in the data list have been changed then an error message: -

            “No data entered”

is displayed, and (unless it contains CONTINUE) the ACCEPT program terminates the program with the screen re-displayed.

MESSAGE (field name) | NOMESSAGE

MESSAGE allows you to name a field to receive the messages.  For web services and 3270 screens there will be a warning message if this field is not in the output message. 

 

NOMESSAGE specifies that there is no validation-message field.

 

If neither of MESSAGE nor NOMESSAGE are given ACCEPT will look for a field called “Error” in the output message.

 

If there is no validation-message field, either because NOMESSAGE is specified or because “Error” couldn’t be found, the ACCEPT will still validate the data and you can test whether errors were found using the BOOLEAN field $Error (which will be qualified to JZ.$Error): -

            ACCEPT (data list)

            IF JZ.$Error THEN;

                           errors were found

            END IF

ACCEPT Validation Logic

ACCEPT checks data based on the definition of the target fields. For example, if CUSTNQY.Account was dragged/dropped into the screen from field CustF.Account then ACCEPT (CUSTNQY.Account); assigns data to field CustF.Account (i.e. CustF.Account is the “target field”), and validation is on the definition of CustF.Account.

 

For each field named (directly or by implication) in the data list, ACCEPT applies the following logic.

 

Part 1. Can the data be assigned to the target field?

Field Type

Checks

CHAR

Value too long for the target field (1)

VARCHAR

Value too long for the target field (1)

Any Number(2)

Value must be numeric.  If the input field is not already numeric, then Jazz checks that the character-format input field can be converted to a number.  If it can, then the value is assigned to the target field. (3)

Other field types

The value will be checked for its format (e.g. a DATE value must be given a valid date),

Validation Options(4)

If the field has passed its initial checks it is assigned to the target field, which is then checked according to any optional attributes like CHECKR, CODES, RANGE, VALUES, WHERE etc. 

 

Notes

1.                  This should be impossible if the screen was generated by Jazz by dragging the field on to it, and neither the screen definition nor the record definition has subsequently been modified.

2.                  “Any Number” means types TINYINT, SMALLINT, INTEGER, BIGINT, DECIMAL, MONEY, FLOAT, LONG, PIC, plus implied numbers such as the indexes of CODES fields.

3.                  With Web Service input the data will already have been checked and converted, according to the rules of the client program and SOAP.  If the client (Windows, Web Page, or App) logic doesn’t prevent non-numeric characters being entered into a numeric field then default SOAP/CICS logic will reject this input and return a SOAPFAULT message.   A record with such faults will not be seen by your Jazz (=COBOL) program.

 

Part 2.  If the data passes this initial check, then it is assigned to the target field.  It is checked further if the Jazz definition requires further validation.  Note that this means data CAN be invalid after an ACCEPT, although you will have been informed through the MESSAGE field and/or $Error.  For example, with this program

PROGRAM LogicV2C BATCH;

DEFINE W DATA(Message VARCHAR(80));

DEFINE In DATA

    (Region DECIMAL(3),

    State CHAR(2));

COPY Types;

DEFINE Out DATA

    (Region DECIMAL(3) RANGE(1:10),

    State LIKE Types.US-State);

In.Region = 123;

In.State = 'xx';

ACCEPT(Out.*= In.*) MESSAGE W.Message;

#207 I Region,State, included in generic assignment

PRINT(Out.*, W.Message) FIELDTABLE;

both Region and State have compatible formats, and so are moved to Out.  However neither is valid, and the PRINT statement reports

 

Field Name  PR-LTH  VALUE                                        

Out.Region:      4: 123                                           

Out.State :     17:xx/**************                             

W.Message :     46:Region outside valid range; State Invalid Code*

 

1.                  Refer to JazzLRM_Data.htm for descriptions of these options.

 

If the field is not valid, then

A.   ACCEPT from 3270 screen

1.                  It’s associated “Error Indicator” character is set to “*”.

2.                  Its length is set to -1 so that the cursor will be positioned at the start of the field. If there are several invalid fields then the cursor will be positioned at the first of them.

B.   All ACCEPT statements with a message field being explicitly or implicitly defined

3.                  An error message such as “Account NOT NUMERIC” is written to the message field.

C.   All ACCEPT statements

4.                  An error flag is set that can be tested with

IF JZ.$Error THEN;

 

When all fields in the list have been checked, then if there are any errors and also the CONTINUE option is not used then program exits.  With 3270 input, the screen is sent back to the terminal with an alarm.

 

If you use CONTINUE with 3270 input then the screen will be set up with the error-indicator and error message, and you can send it later. You can test whether there was an error with a condition using $Error.  You’ll write “$Error”, but this will be qualified to JZ.$Error.  For example: -

          ACCEPT (CUSTNQY.Account) CONTINUE;

           

            If JZ.$Error = ‘Y’ THEN

              

However this field refers to the most recent ACCEPT statement. If you write

          ACCEPT (CUSTNQY.A) CONTINUE;

          ACCEPT (CUSTNQY.B) CONTINUE;

          ACCEPT (CUSTNQY.C);

            If JZ.$Error THEN

               

this will refer ONLY to ACCEPT (CUSTNQY.C);, and so the condition will be false if A and/or B are invalid but C is OK.  You should define your own BOOLEAN field and save the value of $Error after each ACCEPT: -  

DEFINE T DATA(EFlag BOOLEAN);

          ACCEPT (CUSTNQY.A) CONTINUE;

IF JZ.$Error THEN;

    T.EFlag = True;

END IF;

          ACCEPT (CUSTNQY.B) CONTINUE;

IF JZ.$Error THEN;

    T.EFlag = True;

END IF;

          ACCEPT (CUSTNQY.C);

IF JZ.$Error THEN;

    T.EFlag = True;

END IF;

IF T.EFlag THEN;