IBM i Version 7.2. Programming DDS for ICF files IBM

Transcription

1 IBM i Version 7.2 Programming DDS for ICF files IBM

2

3 IBM i Version 7.2 Programming DDS for ICF files IBM

4 Note Before using this information and the product it supports, read the information in Notices on page 43. This edition applies to IBM i 7.2 (product number 5770-SS1) and to all subsequent releases and modifications until otherwise indicated in new editions. This version does not run on all reduced instruction set computer (RISC) models nor does it run on CISC models. This document may contain references to Licensed Internal Code. Licensed Internal Code is Machine Code and is licensed to you under the terms of the IBM License greement for Machine Code. Copyright IBM Corporation 1999, US Government Users Restricted Rights Use, duplication or disclosure restricted by GS DP Schedule Contract with IBM Corp.

5 Contents DDS for ICF files PDF file for DDS for ICF files Defining an ICF file using DDS Sequence number for ICF files (positions 1 through 5) Form type for ICF files (position 6) Comment for ICF files (position 7) Condition for ICF files (positions 7 through 16).. 2 Type of name or specification for ICF files (position 17) Reserved for ICF files (position 18) Name for ICF files (positions 19 through 28)... 4 Reference for ICF files (position 29) Length for ICF files (positions 30 through 34).. 5 Data type for ICF files (position 35) Decimal positions for ICF files (positions 36 and 37) Usage for ICF files (position 38) Location for ICF files (positions 39 through 44).. 7 DDS keyword entries for ICF files (positions 45 through 80) LIS (lternative Name) keyword for ICF files 7 LWWRT (llow Write) keyword for ICF files.. 8 CNCEL (Cancel) keyword for ICF files CNLINVITE (Cancel Invite) keyword for ICF files 9 CONFIRM (Confirm) keyword for ICF files CTLDT (Control Data) keyword for ICF files.. 10 DETCH (Detach) keyword for ICF files DFREVOKE (Defer Evoke) keyword for ICF files 11 ENDGRP (End of Group) keyword for ICF files 12 EOS (End of Session) keyword for ICF files EVOKE (Evoke) keyword for ICF files FIL (Fail) keyword for ICF files FLTPCN (Floating-Point Precision) keyword for ICF files FMH (Function Management Header) keyword for ICF files FMTNME (Format Name) keyword for ICF files 17 FRCDT (Force Data) keyword for ICF files.. 17 INDR (Indicator rea) keyword for ICF files 18 INDTXT (Indicator Text) keyword for ICF files 19 INVITE (Invite) keyword for ICF files NEGRSP (Negative Response) keyword for ICF files PRPCMT (Prepare for Commit) keyword for ICF files RCVCNCEL (Receive Cancel) keyword for ICF files RCVCONFIRM (Receive Confirm) keyword for ICF files RCVCTLDT (Receive Control Data) keyword for ICF files RCVDETCH (Receive Detach) keyword for ICF files RCVENDGRP (Receive End of Group) keyword for ICF files RCVFIL (Receive Fail) keyword for ICF files.. 24 RCVFMH (Receive Function Management Header) keyword for ICF files RCVNEGRSP (Receive Negative Response) keyword for ICF files RCVROLLB (Receive Rollback Response Indicator) keyword for ICF files RCVTKCMT (Receive Take Commit Response Indicator) keyword for ICF files RCVTRNRND (Receive Turnaround) keyword for ICF files RECID (Record Identification) keyword for ICF files REF (Reference) keyword for ICF files REFFLD (Referenced Field) keyword for ICF files 31 RQSWRT (Request Write) keyword for ICF files 32 RSPCONFIRM (Respond Confirm) keyword for ICF files SECURITY (Security) keyword for ICF files SUBDEV (Subdevice) keyword for ICF files SYNLVL (Synchronization Level) keyword for ICF files TEXT (Text) keyword for ICF files TIMER (Timer) keyword for ICF files TNSSYNLVL (Transaction Synchronization Level) keyword for ICF files VRBUFMGT (Variable Buffer Management) keyword for ICF files VRLEN (Variable-Length User Data) keyword for ICF files DBCS considerations for ICF files Positional entry considerations for ICF files that use DBCS dditional considerations for describing ICF files that contain DBCS data Notices Programming interface information Trademarks Terms and conditions Index Copyright IBM Corp. 1999, 2013 iii

6 iv IBM i: Programming

7 DDS for ICF files You can use data description specifications (DDS) to define intersystem communications function (ICF) files. This topic collection provides the information you need to code the positional and keyword entries that define these files. PDF file for DDS for ICF files You can view and print a PDF file of this information. To view or download the PDF version of this document, select DDS for ICF files. Saving PDF files To save a PDF on your workstation for viewing or printing: 1. Right-click the PDF link in your browser. 2. Click the option that saves the PDF locally. 3. Navigate to the directory in which you want to save the PDF. 4. Click Save. Downloading dobe Reader You need dobe Reader installed on your system to view or print these PDFs. You can download a free copy from the dobe Web site ( Defining an ICF file using DDS When you specify positional entries for ICF files, you should follow some specific rules for filling in positions 1 through 44 of the data description specifications (DDS) form. DDS keyword entries for ICF files (positions 45 through 80) on page 7 gives rules and examples for specifying DDS keywords. For more information about keywords for ICF files, see the ICF Programming book. Specify the entries in the following order to define an ICF file: 1. File-level entries 2. Record-level entries 3. Field-level entries Repeat the record-level entries and field-level entries for each record format in the file. Specify at least one record format in the file. The maximum number of record formats in an ICF file is The maximum number of fields in any one record format is Note: Specify the file name with the Create Intersystem Communications Function File (CRTICFF) command, not DDS. Copyright IBM Corp. 1999,

8 The following figure shows an ICF file example * ICF FILE CODING EXMPLE 00020* R RCD1 RCVENDGRP(14) FLD FLDB FLDC R RCD ON74 FIL FLDD 12 FLDC R REFFLD( LIB1/FILE) Figure 1. ICF file example Positional entries for ICF files (positions 1 through 44) Here are some rules and examples for filling in positions 1 through 44 of the data description specifications (DDS) form. To code the remaining part of the form, see DDS keyword entries for ICF files (positions 45 through 80) on page 7. Figure 1 shows some positional entries for ICF files. Related concepts: Rules for DDS keywords and parameter values : n ICF file using DDS DDS concepts Sequence number for ICF files (positions 1 through 5) You can use these positions to specify a sequence number for each line on the form. The sequence number is optional and is for documentation purposes only. Form type for ICF files (position 6) You specify an in this position to identify this as a DDS form. The form type is optional and is for documentation purposes only. Comment for ICF files (position 7) You specify an asterisk (*) in this position to identify this line as a comment. Comment lines can appear anywhere in DDS and are kept only in the source file. They appear on the source computer printout but do not appear on the expanded source computer printout. Use positions 8 through 80 for comment text. blank line (no characters specified in positions 7 through 80) is handled as a comment. Condition for ICF files (positions 7 through 16) Positions 7 through 16 are a multiple-field area in which you can specify option indicators. 2 IBM i: Programming

9 Option indicators are 2-digit numbers from 01 to 99. Your program can set option indicators on (hexadecimal F1) or off (hexadecimal F0) to select a keyword for output operations. In ICF files, option indicators are valid only for record- and file-level keywords. condition is an ND grouping of two through nine indicators that must all be in effect before the keyword is selected. For the indicators to be in effect, they are set off if the letter N is specified, or set on if N is not specified. You can specify a maximum of nine indicators for each condition and nine conditions for each keyword. Therefore, a maximum of 81 indicators can be specified for each keyword, when nine indicators are used with nine conditions. n ND condition occurs when you specify a condition requiring that more than one indicator must be on or off before the condition is satisfied and the keyword is selected. You can join the first indicator with the second, and the third, and so on, by ND to form a condition. You must specify the keyword on the same line as the last (or only) set of indicators specified. You can also specify several conditions for a keyword such that if any one of them is satisfied, the keyword is selected. This is called an OR relationship. You can join the first condition with the second condition, and the third condition, and so on, by OR. Note that conditions within the OR relationship can consist of just one indicator or several indicators joined by ND. Indicators can be joined by ND to form a condition. Conditions can be joined by OR to give your program several ways to select the keyword. Specify the conditions by entering the following values: Position 7 (ND) If you need more than three indicators to form an ND condition, specify the indicators on the next line or lines. You can specify an in position 7 on the second or following lines to continue the ND condition, or you can leave it blank because is the default. Position 7 (OR) If you specify several conditions that are to be joined together by OR, each condition must start on a new line and each condition, except the first, must have an O in position 7. n O specified for the first condition produces a warning message, and that position is assumed to be blank. Positions 8, 11, 14 (NOT) If you want an indicator to be off instead of on to satisfy a condition, specify an N in the position just preceding the indicator (position 8, 11, or 14). Specifying a condition for more than one keyword for ICF files If you want to specify a condition for one or more keywords, the last (or only) indicator must appear on the same line as the keywords. If the condition applies to keywords on more than one line, you must use keyword continuation for the indicators to apply to all keywords. Related information: Rules for DDS keywords and parameter values Type of name or specification for ICF files (position 17) You can enter a value in this position to identify the type of name specified in positions 19 through 28. The valid entries for ICF files are: Entry R Blank Meaning Record format name Field name The ICF file example in Defining an ICF file using DDS shows how to code the name type. DDS for ICF files 3

10 Related reference: Name for ICF files (positions 19 through 28) You can use these positions to specify record format names and field names. Reserved for ICF files (position 18) This position does not apply to any file type. Leave this position blank unless you use it for comment text. Name for ICF files (positions 19 through 28) You can use these positions to specify record format names and field names. Names must begin in position 19. Record format name for ICF files When you specify an R in position 17, the name specified in positions 19 through 28 is a record format name. You can specify more than one record format for an ICF file, but each record format name must be unique within that file. Field name for ICF files When you specify a blank in position 17, the name specified in positions 19 through 28 is a field name. Field names must be unique within the record format. For ICF files, the order in which field names are specified in the DDS is the order the fields take in the input and output buffers. The keywords CNCEL, EOS, FIL, and RQSWRT must have option indicators when they apply to a record with fields. Fields are ignored at run time (not sent across the line) when any of these keywords are in effect. t creation time, if any of these keywords have no option indicator and apply to a record with fields, a severe error is issued and the file will not be created. Related reference: Type of name or specification for ICF files (position 17) on page 3 You can enter a value in this position to identify the type of name specified in positions 19 through 28. Related information: Rules for DDS keywords and parameter values Reference for ICF files (position 29) You specify an R in this position to use the reference function of the program. This function copies the attributes of a previously defined, named field (called the referenced field) to the field you are defining. The referenced field can be previously defined in the ICF file you are defining. The referenced field can also be defined in a previously created database file (the database file to be referenced is specified with the REF or REFFLD keyword). The field attributes referenced are the length, data type, and decimal positions of the field, as well as the LIS, FLTPCN, and TEXT keywords. If you do not specify R, you cannot use the reference function for this field and you must specify field attributes for this field. Position 29 must be blank at the file and record levels. The name of the referenced field can be either the same as the field you are defining or different from the field you are defining. If the name of the referenced field is the same as the field you are defining, you need only specify the letter R in position 29 (in addition to specifying the name of the field you are 4 IBM i: Programming

11 defining in positions 19 through 28). If the name of the field you are defining is different, you must specify the name of the referenced field with the REFFLD (Referenced Field) keyword. You can specify the name of the file defining the referenced field as a parameter value with the REF or REFFLD keyword. You do not need to copy all attributes from the previously described field to the field you are defining. To override specific attributes of the referenced field, specify those attributes for the field you are defining. For example, if you specify a length for the field you are defining, the length is not copied from the referenced field. When you override the data type to character (by specifying in position 35), the decimal positions value is not copied from the referenced field. Note: fter the ICF file is created, you can delete or change the referenced file without affecting the field descriptions in the ICF file. Delete and re-create the ICF file to incorporate changes made in the referenced file. Related reference: REF (Reference) keyword for ICF files on page 30 You can use this file-level keyword to specify the name of a file from which field descriptions are to be retrieved. REFFLD (Referenced Field) keyword for ICF files on page 31 You can use this field-level keyword when referring to a field under one of these conditions. Related information: When to specify REF and REFFLD keywords for DDS files Length for ICF files (positions 30 through 34) You must specify the field length for each field (unless you copy the field's attributes from a referenced field). Specify the number of digits for a numeric field, or the number of characters for a character field. The length specification must be right-aligned; leading zeros are optional. Valid length specifications for ICF files are as follows: Data type Valid length Character 1 through Binary 1 through 9 Zoned decimal 1 through 63 Packed decimal 1 through 63 Floating-point single precision 1 through 9 Floating-point double precision 1 through 17 You can specify a maximum of 9 digits for single precision and 17 digits for double precision. However, the IBM i operating system supports a floating-point accuracy of 7 digits for single precision and 15 digits for double precision. The sum of the number of bytes occupied by all fields in a record must not exceed for ICF files. The system determines the number of bytes actually occupied as follows: Data type Bytes occupied in storage Character Number of characters Binary 1-4 digits 2 bytes 5-9 digits 4 bytes DDS for ICF files 5

12 Data type Zoned decimal Packed decimal Floating-point (single precision) Floating-point (double precision) Bytes occupied in storage Number of digits (Number of digits/2) + 1 (truncated if fractional) 4 bytes 8 bytes If you are using a referenced field, you can override the length of the field by specifying a new value or by specifying the increase or decrease in length. To increase the length, specify +n where n is the increase. To decrease the length, specify -n, where n is the decrease. For example, an entry of +4 for a numeric field indicates that it is to be 4 digits longer than the referenced field. Note: High-level languages can impose specific length and value restrictions on the field length. Observe these restrictions for files used by those languages. Data type for ICF files (position 35) You can use this position to specify the data type of the field within the file. The valid data type entries for ICF files are as follows: Entry P S B F Meaning Packed decimal Zoned decimal Binary Floating-point Character Note: The data type O (DBCS-capable) supports DDS ICF files that use double-byte character set (DBCS). If a data type is not specified for the field and is not duplicated from a referenced field, DDS assigns a default depending on the value in the decimal positions (positions 36 and 37). If the decimal positions are blank, a default of character () is assigned. If the decimal positions contain a number in the range 0 through 31, a default of zoned decimal (S) is assigned. Note: Specifying F in position 35 results in a single precision floating-point field. Use the FLTPCN keyword to specify double precision or to change the precision of an already specified floating-point field. Decimal positions for ICF files (positions 36 and 37) You can use these positions to specify the decimal placement within a packed decimal, a zoned decimal, a floating point, or a binary field. Specify a decimal number from 0 through 31 to indicate the number of decimal positions to the right of the decimal point. (This number must not be greater than the number of digits specified in the field length.) You can override or change these positions if you are using a referenced field. To override the positions, specify the new value. To change the positions, specify the amount by which you want the field increased or decreased and precede it with either a + or -. For example, an entry of +4 indicates there are to be four more digits to the right of the decimal point than were in the referenced field. If the resulting number of decimal positions is greater than the maximum allowed, you will receive an error message. 6 IBM i: Programming

13 Note: High-level languages can impose specific length and value restrictions on the decimal positions. Observe these restrictions for files used by those languages. Usage for ICF files (position 38) The valid entries for this position are listed here. Entry B or blank P Meaning Both input/output field Program-to-system field program-to-system field is used to communicate between an application program and the sending system (which is local to the application program). It is not sent as part of the data record across the line to the receiving system. The following rules apply to program-to-system fields: v The field must be a named, numeric, or alphanumeric output-only field. v In the record format, the program-to-system fields must be defined after all the data fields (those with a use of B or blank). v field cannot be defined as both a data field and a program-to-system field; the field names must be unique. v program-to-system field can be named on an EVOKE, SECURITY, TIMER, or VRLEN keyword. v The only valid keywords for a program-to-system field are LIS, FLTPCN, REFFLD and TEXT. Location for ICF files (positions 39 through 44) These positions do not apply to ICF files. Leave these positions blank unless you use them for comment text. DDS keyword entries for ICF files (positions 45 through 80) The keyword entries are specified in positions 45 through 80. Be sure to follow the rules for DDS keywords and parameter values. Related information: Rules for DDS keywords and parameter values LIS (lternative Name) keyword for ICF files You can use this field-level keyword to specify an alternative name for a field. When the program is compiled, the alternative name is brought into the program instead of the DDS field name. The high-level language compiler in use determines whether the LIS name is used. Refer to the appropriate high-level language reference manual for information about LIS support for that language. The format of the keyword is: LIS(alternative-name) For LIS naming conventions, see DDS naming conventions. The alternative-name must be different from all other alternative names and from all DDS field names in the record format. If a duplicate name is found, an error is issued on the field name or alternative name. DDS for ICF files 7

14 n alternative name cannot be used within DDS or any other IBM i function (for example, as a key field name, as the field name specified for the REFFLD keyword, or as a field name used in the Copy File (CPYF) command). When you refer to a field that has the LIS keyword, the LIS keyword is copied in unless the LIS keyword is explicitly specified on the referencing field. Option indicators are not valid for this keyword. The following example shows how to specify the LIS keyword FIELD 25 LIS(CUSTOMERNME) Related information: DDS naming conventions LWWRT (llow Write) keyword for ICF files You can use this file- or record-level keyword to allow your program to indicate when it has finished sending data. This keyword has no parameters. LWWRT is ignored at run time when DETCH, EOS, RSPCONFIRM, or RQSWRT keyword is in effect. These keywords must have option indicators if they apply to a record for which LWWRT applies. If a DETCH, EOS, RSPCONFIRM, or RQSWRT keyword with no option indicator applies to a record for which LWWRT applies, an error message is issued and the LWWRT keyword is ignored at creation time. You cannot specify LWWRT with the TIMER keyword. The LWWRT keyword can be specified once at the file level or once for each record format. Option indicators are valid with this keyword. When you specify this keyword at the file level, you should specify an option indicator. The following example shows how to specify the LWWRT keyword LWWRT R CUSMST CNCEL (Cancel) keyword for ICF files You can use this file- or record-level keyword to cancel the current chain of data (group of records) that is being sent to the remote program. This keyword has no parameters. The CNCEL keyword must have an option indicator when it applies to a record for which any of the following keywords apply: 8 IBM i: Programming

15 CNLINVITE EVOKE RQSWRT RSPCONFIRM VRBUFMGT VRLEN Data fields and these keywords are ignored at run time when the CNCEL keyword is in effect. If a CNCEL keyword with no option indicator applies to a record for which any of these keywords apply, error messages are issued and these keywords are ignored at creation time. If a CNCEL keyword with no option indicator applies to a record with data fields, a severe error is issued and the file is not created. The CNCEL keyword is ignored at run time when EOS, FIL, or NEGRSP is in effect. These keywords must have option indicators if they apply to a record for which CNCEL applies. If a EOS, FIL, or NEGRSP keyword with no option indicator applies to a record for which CNCEL applies, an error message is issued and the CNCEL keyword is ignored at creation time. You cannot specify CNCEL with the TIMER keyword. Option indicators are valid for this keyword. The following example shows how to specify the CNCEL keyword. 02 CNCEL R RCD1 CNLINVITE (Cancel Invite) keyword for ICF files You can use this file- or record-level keyword to cancel any valid invite operation for which no input has yet been received. This keyword has no parameters. The CNLINVITE keyword must have an option indicator when it applies to a record for which a RQSWRT, RSPCONFIRM, or EVOKE keyword applies. t run time, these keywords are ignored when CNLINVITE is in effect. If a CNLINVITE keyword with no option indicator applies to a record for which any of these keywords apply, error messages are issued and these keywords are ignored at creation time. The CNLINVITE keyword is ignored at run time when CNCEL, EOS, FIL, or NEGRSP is in effect. These keywords must have option indicators when they apply to a record for which the CNLINVITE keyword applies. If a CNCEL, EOS, FIL, or NEGRSP keyword with no option indicator applies to a record for which CNLINVITE applies, an error message is issued and the CNLINVITE keyword is ignored at creation time. You cannot specify CNLINVITE with the TIMER keyword. Option indicators are valid for this keyword. The following example shows how to specify the CNLINVITE keyword R RCD1 CNLINVITE DDS for ICF files 9

16 CONFIRM (Confirm) keyword for ICF files You can use this file- or record-level keyword to request the remote program to confirm that it received the data. This keyword has no parameters. The CONFIRM keyword is valid only if the transaction was established with a synchronization level of confirm (SYNLVL(*CONFIRM) keyword). If the transaction was established with a synchronization level of none (SYNLVL(*NONE) keyword), the CONFIRM keyword is rejected with an IBM i error message. The CONFIRM keyword is ignored at run time when EOS, RSPCONFIRM, or RQSWRT is in effect. These keywords must have option indicators when they apply to a record for which the CONFIRM keyword applies. If an EOS, RSPCONFIRM, or RQSWRT keyword with no option indicator applies to a record for which CONFIRM applies, an error message is issued and the CONFIRM keyword is ignored at creation time. You cannot specify CONFIRM with the TIMER keyword. The CONFIRM keyword can be specified once at the file level or once for every record format. Option indicators are valid with this keyword. The following example shows how to specify the CONFIRM keyword R RCD CONFIRM If option indicator 01 is on, the remote program will confirm receiving the data by sending either a positive or negative response. CTLDT (Control Data) keyword for ICF files You can use this file- or record-level keyword to inform the remote program that control data is being sent. This keyword has no parameters. The CTLDT keyword is ignored at run time when the EOS, RSPCONFIRM, or RQSWRT keyword is in effect. These keywords must have option indicators if they apply to a record for which CTLDT applies. If an EOS, RSPCONFIRM, or RQSWRT keyword with no option indicator applies to a record for which CTLDT applies, an error message is issued and the CTLDT keyword is ignored at creation time. You cannot specify CTLDT with the TIMER keyword. Option indicators are valid for this keyword. The following example shows how to specify the CTLDT keyword at the record level. R SNDCTLD CTLDT USRSCTLD IBM i: Programming

17 DETCH (Detach) keyword for ICF files You can use this file- or record-level keyword to explicitly inform the remote program that your program has completed sending data and wants to end the transaction. This keyword has no parameters. The DETCH keyword must have an option indicator when it applies to a record for which any of the following keywords apply: LWWRT ENDGRP FMH FRCDT INVITE SUBDEV t run time, these keywords are ignored when the DETCH keyword is in effect. If a DETCH keyword with no option indicator applies to a record for which any of these keywords apply, error messages are issued and these keywords are ignored at creation time. The DETCH keyword is ignored at run time when EOS, RSPCONFIRM, or RQSWRT is in effect. These keywords must have option indicators when they apply to a record for which the DETCH keyword applies. If an EOS, RSPCONFIRM, or RQSWRT keyword with no option indicator applies to a record for which DETCH applies, an error message is issued and the DETCH keyword is ignored at creation time. You cannot specify DETCH with the TIMER keyword. t most, the DETCH keyword can be specified once at the file level or once per record format. Option indicators are valid for this keyword. The following example shows how to specify the DETCH keyword R RCD DETCH If option indicator 01 is on, the transaction between your program and the remote program will be ended. DFREVOKE (Defer Evoke) keyword for ICF files You can use this file- or record-level keyword with the EVOKE keyword to delay an evoke request until either the send buffer is full of data or a FRCDT keyword is received. The DFREVOKE keyword is useful only for specialized applications that must have the data sent at the same time as the EVOKE keyword. This keyword has no parameters. You cannot specify DFREVOKE keyword with the TIMER keyword. Option indicators are valid for this keyword. i5/os DDS for ICF files DDS for ICF files 11

18 The following example shows how to specify the DFREVOKE keyword at the record level. R PGMSTRT EVOKE(&LIB/&PGMID); DFREVOKE ENDGRP (End of Group) keyword for ICF files You can use this file- or record-level keyword to allow your program to indicate the end of a user-defined group of records. This keyword has no parameters. The ENDGRP keyword is ignored at run time when DETCH, EOS, RSPCONFIRM, or RQSWRT is in effect. These keywords must have option indicators when they apply to a record for which the ENDGRP keyword applies. If a DETCH, EOS, RSPCONFIRM, or RQSWRT keyword with no option indicator applies to a record for which ENDGRP applies, an error message is issued and the ENDGRP keyword is ignored at creation time. You cannot specify ENDGRP with the TIMER keyword. Option indicators are valid for this keyword. (When you specify this keyword at the file level, you should specify an option indicator.) The following example shows how to specify the ENDGRP keyword R RECORD1 ENDGRP EOS (End of Session) keyword for ICF files You can use this file- or record-level keyword to specify an end of session function. To end a session, your program issues a write operation with the EOS keyword in effect. This keyword has no parameters. The EOS keyword must have an option indicator when it applies to a record for which any of the following keywords apply: LWWRT CNCEL CNLINVITE CONFIRM DETCH ENDGRP EVOKE FIL FMH FMTNME FRCDT INVITE NEGRSP RQSWRT RSPCONFIRM SUBDEV VRBUFMGT VRLEN t run time, data fields and these keywords are ignored when the EOS keyword is in effect. If an EOS keyword with no option indicator applies to a record for which any of these keywords apply, error messages are issued and these keywords are ignored at creation time. If an EOS keyword with no option indicator applies to a record with data fields, a severe error is issued and the file is not created. You cannot specify EOS with the TIMER keyword. 12 IBM i: Programming

19 Option indicators are valid for this keyword. When you specify this keyword at the file level, you should specify an option indicator. The following example shows how to specify the EOS keyword. 01 EOS R RCD If indicator 01 is on and the program does an output operation, the session will be ended. EVOKE (Evoke) keyword for ICF files You can use this file- or record-level keyword to start a program on the remote system. The format of the keyword is: EVOKE([library-/e1e/]program-name [parameter-1...[parameter-255]]) The program-name can be any one of the following: program-name This is the name of the program to be started on the remote system. The name is syntax-checked at creation time for a valid object name. 'character-string-1' This is the name of the program to be started on the remote system. The name you specify must be in a format acceptable to the remote system because the character string will not be syntax-checked. &field-name-1 The specified field contains the name of the program to be started on the remote system. The field name must be a valid field you have specified in the record format and must be a character field (data type of ). The name you specify must be in a format acceptable to the remote system. The optional library-name can be any one of the following: library-name/ This is the name of the library that contains the program to be started on the remote system. The name is syntax-checked at creation time for a valid object name. For this keyword, *CURLIB and *LIBL are not valid names. If either one needs to be specified, a quoted character string should be used. 'character-string-2'/ This is the name of the library that contains the program to be started on the remote system. The name you specify must be in a format acceptable to the remote system because the character string will not be syntax-checked. &field-name-2/ The specified field contains the name of the library that contains the program to be started on the remote system. The field name must be a valid field you have specified in the record format and must be a character field (data type of ). The name you specify must be in a format acceptable to the remote system. Note: If the IBM i operating system is running on the remote system and no library is specified, the library list is used to search for the program. Parameter-1 through parameter-255 can be any of the following: DDS for ICF files 13

20 'character-string-3' This is a character string that is passed to the program on the remote system. The character string must be in a format acceptable to the remote system because it will not be syntax-checked. [&]field-name-3 This is the name of the field that contains the data you want passed to the program on the remote system. The field name must be a valid field you have specified in the record format. numeric-value-3 This is a numeric value that is passed to the program on the remote system. The numeric value can be a negative or positive value (signed or unsigned). decimal point of, or. is optional. No decimal alignment will be performed. Leading zeros will not be suppressed. The data is sent as a zoned decimal value. The following numeric values are all valid: , Special considerations when using the EVOKE keyword with ICF files These are special considerations when using the EVOKE keyword. v When the EVOKE keyword is specified at the file level, you cannot specify a field name as a parameter value. v The maximum length allowed for the combined program name and library name is 64. The slash between the program name and the library name is counted as part of the 64 bytes. dvanced Program-to-Program Communication (PPC) does not send the slash unless it is specified within a literal (for example, LIBRRY/PROGRM). v The total length of parameter-1 through parameter-255 cannot be more than bytes. Note: In calculating the maximum length of PIP data for PPC, keep these considerations in mind: Four bytes must be added to the length of each of these parameters. n additional 4 bytes must be added if any parameters are specified. These bytes are required by the system. Use the following formula to determine the total length of the parameters: 4 + (length of 1st parameter + 4) + (length of 2nd parameter + 4) +... (length of nth parameter + 4) Here is an example of how to use this formula: EVOKE(LIBRRY1/PROGRM1 'THIS IS N EXMPLE OF CHRCTER STRING' &FIELD1 35) ssume that &FIELD1 has a length of (40 + 4) + (10 + 4) + (2 + 4) = 68 v The length of each parameter (parameter-1 through parameter-255) should be the same as the length of the corresponding parameter in the remote program. v If a field name with a usage of P is specified as a parameter of the EVOKE keyword, this field is not sent as part of the data record. v program evoked on the IBM i operating system will receive any parameters sent by the remote program just as if they had been passed by the CL CLL command. 14 IBM i: Programming

21 Note: If the IBM i job is a prestart job, the program must use the Retrieve Data rea (RTVDTR) command to receive the parameters. This keyword is required when either the SECURITY or SYNLVL keyword is specified. t run time, the SECURITY and SYNLVL keywords are used only when EVOKE is also in effect. The EVOKE keyword is ignored at run time when CNCEL, CNLINVITE, EOS, FIL, NEGRSP, RSPCONFIRM, or RQSWRT is in effect. These keywords must have option indicators when they apply to a record for which the EVOKE keyword applies. If a CNCEL, CNLINVITE, EOS, FIL, NEGRSP, or RQSWRT keyword with no option indicator applies to a record for which EVOKE applies, an error message is issued and the EVOKE keyword is ignored at creation time. You cannot specify EVOKE with the TIMER keyword. Option indicators are valid for this keyword and are required if this keyword is specified more than once for each record format or file. The following example shows how to specify the EVOKE keyword R RCD : EVOKE(LIBRRY1/PROGRM1) (1) : EVOKE(LIBRRY2/PROGRM2) (1) : : : : R RCD2 EVOKE(&FIELD2/&FIELD1 BC FIELD3) (2) FIELD1 10 P FIELD2 10 P FIELD3 5B P Note: (1) If indicator 01 is on, PROGRM1 in LIBRRY1 will be started. If indicator 02 is on, PROGRM2 in LIBRRY2 will be started. (2) &FIELD1 contains the name of the program to be started. &FIELD2 contains the name of the library. The character string BC, numeric value 10.1, and the value in FIELD3 will be passed to the program on the remote system. Related reference: SECURITY (Security) keyword for ICF files on page 34 You can use this file- and record-level keyword to include security information when your program starts a program on a remote system. FIL (Fail) keyword for ICF files You can use this file- or record-level keyword to inform the remote program that the data sent or received is not valid. This keyword has no parameters. The FIL keyword must have an option indicator when it applies to a record that has data fields (use of B or blank) or for which any of the following keywords apply: DDS for ICF files 15

22 CNCEL CNLINVITE EVOKE NEGRSP RQSWRT RSPCONFIRM VRBUFMGT VRLEN t run time, data fields and these keywords are ignored when the FIL keyword is in effect. If a FIL keyword with no option indicator applies to a record for which any of these keywords apply, error messages are issued and these keywords are ignored at creation time. If a FIL keyword with no option indicator applies to a record with data fields, a severe error is issued and the file will not be created. The FIL keyword is ignored at run time when the EOS keyword is in effect. EOS must have an option indicator when it applies to a record for which the FIL keyword applies. If an EOS keyword with no option indicator applies to a record for which FIL applies, an error message is issued and the FIL keyword is ignored at creation time. FIL cannot be specified with the TIMER keyword. Option indicators are valid for this keyword. When you specify this keyword at the file level, you should specify an option indicator. The following example shows how to specify the FIL keyword R INQ FIL FLTPCN (Floating-Point Precision) keyword for ICF files You can use this field-level keyword to specify the precision of a floating-point field. The format of the keyword is: FLTPCN(*SINGLE *DOUBLE) where the *SINGLE parameter is single precision and the *DOUBLE parameter is double precision. This keyword is valid for floating-point fields only (data type F). single-precision field can be up to 9 digits. double-precision field can be up to 17 digits. If you specify a field length greater than 9 (single precision) or 17 (double precision), an error message is issued and the file is not created. ICF supports a floating-point accuracy of 7 digits for single precision and 15 digits for double precision. Option indicators are not valid for this keyword. The following example shows how to specify the FLTPCN keyword FIELD 17F 4 FLTPCN(*DOUBLE) 16 IBM i: Programming

23 FMH (Function Management Header) keyword for ICF files You can use this file- or record-level keyword to inform the remote program that a function management header (FMH) is being sent. This keyword has no parameters. The FMH keyword is ignored at run time when EOS, DETCH, RSPCONFIRM, or RQSWRT is in effect. These keywords must have option indicators when they apply to a record for which the FMH keyword applies. If an EOS, DETCH, RSPCONFIRM, or RQSWRT keyword with no option indicator applies to a record for which FMH applies, an error message is issued and the FMH keyword is ignored at creation time. You cannot specify FMH with the TIMER keyword. Option indicators are valid for this keyword. The following example shows how to specify the FMH keyword. R RCD FMH FLD1 10 B FMTNME (Format Name) keyword for ICF files You can use this file- or record-level keyword to specify that the record format name is to be sent to the remote program when your program issues an output operation. This keyword has no parameters. The FMTNME keyword is ignored at run time when EOS, RSPCONFIRM, or RQSWRT is in effect. These keywords must have option indicators when they apply to a record for which the FMTNME keyword applies. If an EOS, RSPCONFIRM, or RQSWRT keyword with no option indicator applies to a record for which FMTNME applies, an error message is issued and the FMTNME keyword is ignored at creation time. You cannot specify FMTNME with the TIMER keyword. Option indicators are valid for this keyword. The following example shows how to specify the FMTNME keyword. R RCD1 01 FMTNME FIELD1 10 B i5/os DDS for ICF files If indicator 01 is on and the program does a write operation, the record format name will be sent as an dvanced Program-to-Program Communication (PPC) map name to the remote system. FRCDT (Force Data) keyword for ICF files You can use this record-level keyword to clear the buffer when there is no more data to send, without waiting for the buffer to become full. DDS for ICF files 17

24 Note: If the keyword is specified after each write statement, performance problems might occur. There is no wait for confirmation. (The CONFIRM keyword provides similar function but additionally provides confirmation of data sent. Your program must wait for the response from the other end before continuing to the next program statement.) This keyword has no parameters. The FRCDT keyword is ignored at run time when any of the following keywords is in effect: DETCH EOS RQSWRT RSPCONFIRM These keywords must have option indicators when they apply to a record specifying FRCDT. If a keyword from this list has no option indicator and applies to a record with FRCDT, an error message is issued and the FRCDT keyword is ignored at creation time. You cannot specify FRCDT with the TIMER keyword. The FRCDT keyword can be specified at most once per record format. Option indicators are valid for this keyword. The following example shows how to specify the FRCDT keyword R REC FRCDT FLD FLD2 5 When option indicator 10 is on and the program does a write operation, the FRCDT keyword sends communications data currently held in the buffer. INDR (Indicator rea) keyword for ICF files You can use this file-level keyword to remove option and response indicators from the buffer or record area, and to place them in a 99-byte separate indicator area. Specifying the INDR keyword provides the following advantages: v Simplifies COBOL/400 programming when both option and response indicators are used. If the same indicator is used as a response indicator and as an option indicator, both indicators always have the same value, regardless of the order in which they are specified in the DDS. v ssists the RPG/400 programmer using program-described workstation (WORKSTN) files. This keyword has no parameters. If you specify the INDR keyword, some high-level languages require that you specify in your program that a separate indicator area is to be used. See the appropriate high-level language manual. If you specify the INDR keyword, you can add, change, or delete option and response indicators in the DDS and recompile the file without recompiling the high-level language program. This is allowed 18 IBM i: Programming

25 because the field locations in the buffer have not changed and, therefore, the level check data has not changed. However, if the program is to take advantage of the new indicators, the program still needs to be changed and recompiled. Option indicators are not valid for this keyword. The following example shows how to specify the INDR keyword INDR FIL RCVTRNRND(14 Turn around ) R RCD CTNBR 10 With the INDR keyword specified, option indicator 41 and response indicator 14 are removed from the buffer for RCD and placed in the separate indicator area. Only CTNBR, a named field, remains in the buffer for record format RCD. INDTXT (Indicator Text) keyword for ICF files You can use this file- or record-level keyword to associate descriptive text (indicating intent or use) with a specific response or option indicator. The format of the keyword is: INDTXT(response-or-option-indicator indicator-text ) You can specify this keyword once for each response and option indicator. Indicator-text is a required parameter value, and must be a character string enclosed in single quotation marks. If the length of the string is greater than 50 positions, only the first 50 characters are used by the high-level language compiler. The text is used during compilation to help program documentation. The INDTXT keyword does not cause the specified indicator to appear in either the input or output record area. It provides text to be associated with the indicator. Once an indicator has been given a textual assignment (either by this keyword or by the response indicator text), no other textual assignment is made. message is issued and the keyword is ignored. This differs from other keywords that can have indicators specified as parameter values; for other keywords, only the text is ignored. Option indicators are not valid for this keyword. The following example shows how to specify the INDTXT keyword INDTXT(02 lternate month ) R MSTER MTH LTMTH 2 10 The INDTXT keyword describes the use of option indicator 02. In a compiler computer printout for a high-level language, alternate month is printed as a comment with the description of indicator 02. DDS for ICF files 19

26 INVITE (Invite) keyword for ICF files You can use this file- or record-level keyword to invite the program device for a later read operation. To send an invite request to the program device, your program issues a write operation to that program device with the INVITE keyword in effect. The INVITE keyword provides some performance improvement if your application program is doing interactive processing with the program device. Normally, a read request is sent to a device when your program issues an input operation. However, the INVITE keyword allows you to request the read operation when you issue the output operation. fter the output operation is completed, your program can do other processing while the invited program device is sending data and the IBM i program processes the received data. This might improve the performance of your program. When your application program is ready to process the data, it issues an input operation. This keyword has no parameters. The INVITE keyword is ignored at run time when EOS, RSPCONFIRM, or DETCH is in effect. These keywords must have option indicators when they apply to a record for which the INVITE keyword applies. If an EOS, RSPCONFIRM, or DETCH keyword with no option indicator applies to a record for which INVITE applies, an error message is issued and the INVITE keyword is ignored at creation time. You cannot specify INVITE with the TIMER keyword. Option indicators are valid for this keyword. The INVITE keyword cannot be specified at both the file- and record-level. The following example shows how to specify the INVITE keyword INVITE R RCD FLD FLD2 5 The INVITE keyword is in effect only when option indicator 01 is set on. NEGRSP (Negative Response) keyword for ICF files You can use this file- or record-level keyword to send a negative response to the remote program. The response indicates that your program detected an error in the data received. The format of the keyword is: NEGRSP[(&field-name)] The optional parameter, &field-name, specifies the name of a field that contains sense data to be sent to the remote program with the negative response. The specified field name must exist in the record format, and the field must be a character field with a length of at least 8, data type, and usage B or blank. The NEGRSP keyword must have an option indicator when it applies to a record for which any of the following keywords apply: 20 IBM i: Programming

27 CNCEL CNLINVITE EVOKE RQSWRT RSPCONFIRM VRBUFMGT VRLEN t run time, these keywords are ignored when the NEGRSP keyword is in effect. If a NEGRSP keyword with no option indicator applies to a record for which any of these keywords apply, error messages are issued and these keywords are ignored at creation time. NEGRSP is ignored at run time when EOS or FIL is in effect. These keywords must have option indicators if they apply to a record for which NEGRSP applies. If an EOS or FIL keyword with no option indicator applies to a record for which NEGRSP applies, an error message is issued and the NEGRSP keyword is ignored at creation time. When you specify NEGRSP at the file level, you cannot specify the field name parameter. You cannot specify NEGRSP with the TIMER keyword. Option indicators are valid for this keyword. The following example shows how to specify the NEGRSP keyword. R RCD1 01 NEGRSP(&FIELDB); FIELD 25 B FIELDB 80 B If indicator 01 is on, a write operation to RCD1 will send a negative response and send the first 8 bytes of FIELDB to the remote program. Note that no data from RCD1 other than the sense data will be sent with the negative response. PRPCMT (Prepare for Commit) keyword for ICF files You can use this record-level keyword to request the remote program to prepare for a synchronization point. n output operation with the PRPCMT keyword specified forces any data in the output buffer to be sent. This keyword has no parameters. When this operation does not complete, your program does not continue until a response is received. The remote program must perform a commit or rollback operation or issue a FIL or EOS to indicate whether it is prepared to commit its protected resources. PRPCMT is only valid with a synchronization level of *COMMIT specified on the EVOKE keyword. The only keywords that can be specified with the PRPCMT keyword are VRBUFMGT and VRLEN. Option indicators are valid for this keyword. The following example shows how to specify the PRPCMT keyword. DDS for ICF files 21