Accessing Single Device Files and Multiple Device Files
A single device file is a device file created with only one program device defined for it. Printer files, diskette files and tape files are single device files. Display files and Intersystem Communication Function (ICF) files created with a maximum number of one program device are also single device files.
A multiple device file is either a display file or an Intersystem Communications Function (ICF) file. A multiple device file can acquire more than one program device. For an example of the use of multiple device files, see Figure 4.
A display file can have multiple program devices when the MAXDEV parameter of the CRTDSPF command is greater than 1. If you specify *NONE for the DEV parameter of this command, you must supply the name of a display device before you use any fields that are related to the file.
For more information about how to create and use a display file, refer to the Database and File Systems category in the IBM i Information Center at this Web site -http://www.ibm.com/systems/i/infocenter/.
ICF files can have multiple program devices when the MAXPGMDEV parameter of the CRTICFF command is greater than 1. For more information about how to create and use ICF files, see the ICF Programming.
ILE COBOL determines at run time whether a file is a single device file or a multiple device file, based on whether the file is capable of having multiple devices. The actual number of devices acquired does not affect whether a file is considered a single or multiple device file. Whether a file is a single or a multiple device file is not determined at compilation time; this determination is based on the current description of the display or ICF file.
For multiple device files, if a particular program device is to be used in an I/O statement, that device is specified by the TERMINAL phrase. The TERMINAL phrase can also be specified for a single device file.
The following pages contain an example illustrating the use of multiple device files. The program uses a display file, and is intended to be run in batch mode. The program acquires terminals and invites those terminals using a sign-on display. After the terminals are invited, they are polled. If nobody signs on before the wait time expires, the program ends. If you enter a valid password, you are allowed to update an employee file by calling another ILE COBOL program. Once the update is complete, the device is invited again and the terminals are polled again.
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....
A* THIS IS THE MULTIPLE DEVICE DISPLAY FILE
A*
A* DDS FOR THE MIXED FILE MULT
A*
A
A R SIGNON INVITE 1
A O 5 20' '
A DSPATR(RI)
A O 6 20' '
A DSPATR(RI)
A O 6 38' '
A DSPATR(RI)
A O 7 20' '
A DSPATR(RI)
A O 7 27'M D F'
A DSPATR(HI BL)
A O 7 38' '
A DSPATR(RI)
A O 9 20' '
A DSPATR(RI)
A O 20 20'PLEASE LOGON'
A DSPATR(HI)
A PASSWORD 10A I 20 43DSPATR(PC ND)
A WRONG 20A O 21 43
A
A R UPDATE
A O 3 5'UPDATE OF PERSONNEL FILE'
A DSPATR(BL)
A O 7 5'TYPE IN EMPLOYEE NUMBER TO BE +
A UPDATED'
A NUM 7A I 7 44DSPATR(RI PC)
A
A R EMPLOYEE
A O 3 5'EMPLOYEE NUMBER'
A NUM 7A B 3 25DSPATR(PC)
A O 5 5'EMPLOYEE NAME'
A NAME 30A B 5 25DSPATR(PC)
A O 7 5'EMPLOYEE ADDRESS'
A O 9 5'STREET'
A STREET 30A B 9 25DSPATR(PC)
A O 11 5'APARTMENT NUMBER'
A APTNO 5A B 11 25DSPATR(PC)
A O 13 5'CITY'
A CITY 20A B 13 25DSPATR(PC)
A O 15 5'PROVINCE'
A PROV 20A B 15 25DSPATR(PC)
A
A R RECOVERY
A O 3 5'THE EMPLOYEE NUMBER YOU HAVE GIVEN
A IS INVALID'
A O 6 5'TYPE Y TO RETRY'
A O 8 5'TYPE N TO EXIT'
A ANSWER 1X I 10 5DSPATR(RI PC)
A VALUES('Y' 'N')1 Â The format SIGNON has the keyword INVITE associated with it. This means that, if format SIGNON is used in a WRITE statement, the device to which it is writing will be invited.
....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....
A** DDS FOR THE PHYSICAL FILE PASSWORD
A*
A*
A UNIQUE
A R PASSWORDS
A PASSKEY 10
A PASSWORD 10
A K PASSKEY
A ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....
A* DDS FOR THE PHYSICAL FILE TERM
A* WHICH CONTAINS THE LIST OF TERMINALS
A*
A
A R TERM
A TERM 10 5722WDS V5R4M0 060210 LN IBM ILE COBOL CBLGUIDE/SAMPMDF ISERIES1 06/02/15 15:04:02 Page 2
S o u r c e
STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 000100 IDENTIFICATION DIVISION.
2 000200 PROGRAM-ID. SAMPMDF.
000300
000400**************************************************************
000500* THE FOLLOWING PROGRAM DEMONSTRATES SOME OF THE FUNCTIONS *
000600* AVAILABLE WITH MULTIPLE DEVICE FILE SUPPORT. *
000700**************************************************************
000800
3 000900 ENVIRONMENT DIVISION.
4 001000 CONFIGURATION SECTION.
5 001100 SOURCE-COMPUTER. IBM-ISERIES
6 001200 OBJECT-COMPUTER. IBM-ISERIES
7 001300 SPECIAL-NAMES. ATTRIBUTE-DATA IS ATTR. 1
9 001400 INPUT-OUTPUT SECTION.
10 001500 FILE-CONTROL.
11 001600 SELECT MULTIPLE-FILE
12 001700 ASSIGN TO WORKSTATION-MULT
13 001800 ORGANIZATION IS TRANSACTION 2
14 001900 ACCESS MODE IS SEQUENTIAL
15 002000 FILE STATUS IS MULTIPLE-FS1, MULTIPLE-FS2 3
16 002100 CONTROL-AREA IS MULTIPLE-CONTROL-AREA. 4
002200
17 002300 SELECT TERMINAL-FILE
18 002400 ASSIGN TO DATABASE-TERM
19 002500 ORGANIZATION IS SEQUENTIAL
20 002600 ACCESS IS SEQUENTIAL
21 002700 FILE STATUS IS TERMINAL-FS1.
002800
22 002900 SELECT PASSWORD-FILE
23 003000 ASSIGN TO DATABASE-PASSWORD
24 003100 ORGANIZATION IS INDEXED
25 003200 RECORD KEY IS EXTERNALLY-DESCRIBED-KEY
26 003300 ACCESS MODE IS RANDOM
27 003400 FILE STATUS IS PASSWORD-FS1.
003500
28 003600 SELECT PRINTER-FILE
29 003700 ASSIGN TO PRINTER-QPRINT.
003800
30 003900 DATA DIVISION.
31 004000 FILE SECTION.
32 004100 FD MULTIPLE-FILE.
33 004200 01 MULTIPLE-REC.
004200 COPY DDS-SIGNON OF MULT. 5
34 +000001 05 MULT-RECORD PIC X(20). SIGNON
+000002* INPUT FORMAT:SIGNON FROM FILE MULT OF LIBRARY CBLGUIDE SIGNON
+000003* SIGNON
35 +000004 05 SIGNON-I REDEFINES MULT-RECORD. SIGNON
36 +000005 06 PASSWORD PIC X(10). 6 SIGNON
+000006* OUTPUT FORMAT:SIGNON FROM FILE MULT OF LIBRARY CBLGUIDE SIGNON
+000007* SIGNON
37 +000008 05 SIGNON-O REDEFINES MULT-RECORD. SIGNON
38 +000009 06 WRONG PIC X(20). SIGNON
004300 5722WDS V5R4M0 060210 LN IBM ILE COBOL CBLGUIDE/SAMPMDF ISERIES1 06/02/15 15:04:02 Page 3
STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
39 004400 FD TERMINAL-FILE.
40 004500 01 TERMINAL-REC.
004500 COPY DDS-ALL-FORMATS OF TERM.
41 +000001 05 TERM-RECORD PIC X(10). <-ALL-FMTS
+000002* I-O FORMAT:TERM FROM FILE TERM OF LIBRARY CBLGUIDE <-ALL-FMTS
+000003* <-ALL-FMTS
42 +000004 05 TERM REDEFINES TERM-RECORD. <-ALL-FMTS
43 +000005 06 TERM PIC X(10). <-ALL-FMTS
004600
44 004700 FD PASSWORD-FILE.
45 004800 01 PASSWORD-REC.
004800 COPY DDS-ALL-FORMATS OF PASSWORD.
46 +000001 05 PASSWORD-RECORD PIC X(20). <-ALL-FMTS
+000002* I-O FORMAT:PASSWORDS FROM FILE PASSWORD OF LIBRARY CBLGUIDE <-ALL-FMTS
+000003* <-ALL-FMTS
+000004*THE KEY DEFINITIONS FOR RECORD FORMAT PASSWORDS <-ALL-FMTS
+000005* NUMBER NAME RETRIEVAL ALTSEQ <-ALL-FMTS
+000006* 0001 PASSKEY ASCENDING NO <-ALL-FMTS
47 +000007 05 PASSWORDS REDEFINES PASSWORD-RECORD. <-ALL-FMTS
48 +000008 06 PASSKEY PIC X(10). <-ALL-FMTS
49 +000009 06 PASSWORD PIC X(10). <-ALL-FMTS
004900
50 005000 FD PRINTER-FILE.
51 005100 01 PRINTER-REC.
52 005200 05 PRINTER-RECORD PIC X(132).
005300
53 005400 WORKING-STORAGE SECTION.
005500
005600**************************************************************
005700* DECLARE THE FILE STATUS FOR EACH FILE *
005800**************************************************************
005900
54 006000 01 MULTIPLE-FS1 PIC X(2) VALUE SPACES.
55 006100 01 MULTIPLE-FS2. 7
56 006200 05 MULTIPLE-MAJOR PIC X(2) VALUE SPACES.
57 006300 05 MULTIPLE-MINOR PIC X(2) VALUE SPACES.
58 006400 01 TERMINAL-FS1 PIC X(2) VALUE SPACES.
59 006500 01 PASSWORD-FS1 PIC X(2) VALUE SPACES.
006600
006700**************************************************************
006800* DECLARE STRUCTURE FOR HOLDING FILE ATTRIBUTES *
006900**************************************************************
007000
60 007100 01 STATION-ATTR.
61 007200 05 STATION-TYPE PIC X(1). 8
62 007300 05 STATION-SIZE PIC X(1).
63 007400 05 STATION-LOC PIC X(1).
64 007500 05 FILLER PIC X(1).
65 007600 05 STATION-ACQUIRE PIC X(1).
66 007700 05 STATION-INVITE PIC X(1).
67 007800 05 STATION-DATA PIC X(1).
68 007900 05 STATION-STATUS PIC X(1).
69 008000 05 STATION-DISPLAY PIC X(1).
70 008100 05 STATION-KEYBOARD PIC X(1).
71 008200 05 STATION-SIGNON PIC X(1). 5722WDS V5R4M0 060210 LN IBM ILE COBOL CBLGUIDE/SAMPMDF ISERIES1 06/02/15 15:04:02 Page 4
STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
72 008300 05 FILLER PIC X(5).
008400
008500**************************************************************
008600* DECLARE THE CONTROL AREA FOR MULTIPLE-FILE *
008700**************************************************************
008800
73 008900 01 MULTIPLE-CONTROL-AREA.
74 009000 05 MULTIPLE-KEY-FEEDBACK PIC X(2) VALUE SPACES.
75 009100 05 MULTIPLE-DEVICE-NAME PIC X(10) VALUE SPACES.
76 009200 05 MULTIPLE-FORMAT-NAME PIC X(10) VALUE SPACES.
009300
009400**************************************************************
009500* DECLARE ERROR REPORT VARIABLES *
009600**************************************************************
009700
77 009800 01 HEADER-LINE.
78 009900 05 FILLER PIC X(60) VALUE SPACES.
79 010000 05 FILLER PIC X(72)
010100 VALUE "MDF ERROR REPORT".
80 010200 01 DETAIL-LINE.
81 010300 05 FILLER PIC X(15) VALUE SPACES.
82 010400 05 DESCRIPTION PIC X(25) VALUE SPACES.
83 010500 05 DETAIL-VALUE PIC X(92) VALUE SPACES.
010600
010700**************************************************************
010800* DECLARE COUNTERS, FLAGS AND STORAGE VARIABLES *
010900**************************************************************
011000
84 011100 01 CURRENT-TERMINAL PIC X(10) VALUE SPACES.
85 011200 01 TERMINAL-ARRAY.
86 011300 05 LIST-OF-TERMINALS OCCURS 250 TIMES.
87 011400 07 DEVICE-NAME PIC X(10).
88 011500 01 COUNTER PIC 9(3) VALUE IS 1.
89 011600 01 NO-OF-TERMINALS PIC 9(3) VALUE IS 1.
90 011700 01 TERMINAL-LIST-FLAG PIC 1.
91 011800 88 END-OF-TERMINAL-LIST VALUE IS B"1".
92 011900 88 NOT-END-OF-TERMINAL-LIST VALUE IS B"0".
93 012000 01 NO-DATA-FLAG PIC 1.
94 012100 88 NO-DATA-AVAILABLE VALUE IS B"1".
95 012200 88 DATA-AVAILABLE VALUE IS B"0".
012300
96 012400 PROCEDURE DIVISION.
012500
97 012600 DECLARATIVES.
012700
012800 MULTIPLE-SECTION SECTION.
012900 USE AFTER STANDARD EXCEPTION PROCEDURE ON MULTIPLE-FILE.
013000
013100 MULTIPLE-PARAGRAPH.
98 013200 WRITE PRINTER-REC FROM HEADER-LINE AFTER ADVANCING PAGE.
99 013300 MOVE "FILE NAME IS:" TO DESCRIPTION OF DETAIL-LINE.
100 013400 MOVE "MULTIPLE FILE" TO DETAIL-VALUE OF DETAIL-LINE.
101 013500 WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 5 LINES.
102 013600 MOVE "FILE STATUS IS:" TO DESCRIPTION OF DETAIL-LINE.
103 013700 MOVE MULTIPLE-FS1 TO DETAIL-VALUE OF DETAIL-LINE. 5722WDS V5R4M0 060210 LN IBM ILE COBOL CBLGUIDE/SAMPMDF ISERIES1 06/02/15 15:04:02 Page 5
STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
104 013800 WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
105 013900 MOVE "EXTENDED STATUS IS:" TO DESCRIPTION OF DETAIL-LINE. 9
106 014000 MOVE MULTIPLE-FS2 TO DETAIL-VALUE OF DETAIL-LINE.
107 014100 WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
108 014200 ACCEPT STATION-ATTR FROM ATTR. 10
109 014300 MOVE "FILE ATTRIBUTES ARE:" TO DESCRIPTION OF DETAIL-LINE.
110 014400 MOVE STATION-ATTR TO DETAIL-VALUE OF DETAIL-LINE.
111 014500 WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
112 014600 STOP RUN.
014700
014800 TERMINAL-SECTION SECTION.
014900 USE AFTER STANDARD EXCEPTION PROCEDURE ON TERMINAL-FILE.
015000 TERMINAL-PARAGRAPH.
113 015100 WRITE PRINTER-REC FROM HEADER-LINE AFTER ADVANCING PAGE.
114 015200 MOVE "FILE NAME IS:" TO DESCRIPTION OF DETAIL-LINE.
115 015300 MOVE "TERMINAL FILE" TO DETAIL-VALUE OF DETAIL-LINE.
116 015400 WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 5 LINES.
117 015500 MOVE "FILE STATUS IS:" TO DESCRIPTION OF DETAIL-LINE.
118 015600 MOVE TERMINAL-FS1 TO DETAIL-VALUE OF DETAIL-LINE.
119 015700 WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
120 015800 STOP RUN.
015900
016000 PASSWORD-SECTION SECTION.
016100 USE AFTER STANDARD EXCEPTION PROCEDURE ON PASSWORD-FILE.
016200 PASSWORD-PARAGRAPH.
121 016300 WRITE PRINTER-REC FROM HEADER-LINE AFTER ADVANCING PAGE.
122 016400 MOVE "FILE NAME IS:" TO DESCRIPTION OF DETAIL-LINE.
123 016500 MOVE "PASSWORD FILE" TO DETAIL-VALUE OF DETAIL-LINE.
124 016600 WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 5 LINES.
125 016700 MOVE "FILE STATUS IS:" TO DESCRIPTION OF DETAIL-LINE.
126 016800 MOVE PASSWORD-FS1 TO DETAIL-VALUE OF DETAIL-LINE.
127 016900 WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
128 017000 STOP RUN.
017100
017200 END DECLARATIVES.
017300
017400**************************************************************
017500* MAIN PROGRAM LOGIC BEGINS HERE *
017600**************************************************************
017700
017800 MAIN-PROGRAM SECTION.
017900 MAINLINE.
129 018000 OPEN I-O MULTIPLE-FILE 11
018100 INPUT TERMINAL-FILE
018200 I-O PASSWORD-FILE
018300 OUTPUT PRINTER-FILE.
018400
130 018500 MOVE 1 TO COUNTER.
131 018600 SET NOT-END-OF-TERMINAL-LIST TO TRUE.
018700******
018800* Fill Terminal List
018900******
132 019000 PERFORM UNTIL END-OF-TERMINAL-LIST
133 019100 READ TERMINAL-FILE RECORD
019200 INTO LIST-OF-TERMINALS(COUNTER) 5722WDS V5R4M0 060210 LN IBM ILE COBOL CBLGUIDE/SAMPMDF ISERIES1 06/02/15 15:04:02 Page 6
STMT PL SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
019300 AT END
134 019400 SET END-OF-TERMINAL-LIST TO TRUE
135 019500 SUBTRACT 1 FROM COUNTER
136 019600 MOVE COUNTER TO NO-OF-TERMINALS
019700 END-READ
137 019800 ADD 1 TO COUNTER
019900 END-PERFORM.
020000******
020100* Acquire and invite terminals
020200******
138 020300 PERFORM VARYING COUNTER FROM 1 BY 1
020400 UNTIL COUNTER GREATER THAN NO-OF-TERMINALS
139 020500 ACQUIRE LIST-OF-TERMINALS(COUNTER) FOR MULTIPLE-FILE 12
140 020600 WRITE MULTIPLE-REC 13
020700 FORMAT IS "SIGNON"
020800 TERMINAL IS LIST-OF-TERMINALS(COUNTER)
020900 END-WRITE
021000 END-PERFORM.
021100
141 021200 MOVE 1 TO COUNTER.
142 021300 SET DATA-AVAILABLE TO TRUE.
021400******
021500* Poll terminals
021600******
143 021700 PERFORM UNTIL NO-DATA-AVAILABLE
144 021800 READ MULTIPLE-FILE RECORD 14
145 021900 IF MULTIPLE-FS2 EQUAL "310" THEN
146 022000 SET NO-DATA-AVAILABLE TO TRUE 15
022100 END-IF
147 022200 IF DATA-AVAILABLE THEN
148 022300 MOVE MULTIPLE-DEVICE-NAME TO CURRENT-TERMINAL
022400******
022500* Validate Password 16
022600******
149 022700 MOVE CURRENT-TERMINAL TO PASSKEY OF PASSWORD-REC
150 022800 READ PASSWORD-FILE RECORD
151 022900 IF PASSWORD OF SIGNON-I EQUAL
023000 PASSWORD OF PASSWORD-REC THEN
152 023100 CALL "UPDT" USING CURRENT-TERMINAL
153 023200 MOVE SPACES TO WRONG OF SIGNON-O
023300 ELSE
154 023400 MOVE "INVALID PASSWORD" TO WRONG OF SIGNON-O
023500 END-IF
155 023600 WRITE MULTIPLE-REC
023700 FORMAT IS "SIGNON"
023800 TERMINAL IS CURRENT-TERMINAL
023900 END-WRITE
024000 END-IF
024100 END-PERFORM.
024200******
024300* Drop terminals
024400******
156 024500 PERFORM VARYING COUNTER FROM 1 BY 1
024600 UNTIL COUNTER GREATER THAN NO-OF-TERMINALS
157 024700 DROP LIST-OF-TERMINALS(COUNTER) FROM MULTIPLE-FILE 17
024800 END-PERFORM.
024900
158 025000 CLOSE MULTIPLE-FILE
025100 TERMINAL-FILE
025200 PASSWORD-FILE
025300 PRINTER-FILE.
159 025400 STOP RUN.
025500
* * * * * E N D O F S O U R C E * * * * *- 1
- ATTR is the mnemonic-name associated with the function-name ATTRIBUTE-DATA. ATTR is used in the ACCEPT statement to obtain attribute data for the TRANSACTION file MULTIPLE-FILE. See item 10 .
- 2
- File MULT must have been created using the CRTDSPF command, where the DEV parameter has a value of *NONE and the MAXDEV parameter has a value greater than 1. The WAITRCD parameter specifies the wait time for READ operations on the file. The WAITRCD parameter must have a value greater than 0.
- 3
- MULTIPLE-FS2 is the extended file status for the TRANSACTION file MULTIPLE-FILE. This variable has been declared in the WORKING-STORAGE section of the program. See item 7 .
- 4
- MULTIPLE-CONTROL-AREA is the control area for the TRANSACTION file MULTIPLE-FILE. This variable is used to determine which program device was used to sign on. See item 15 .
- 5
- The data description for MULTIPLE-REC has been defined using the
COPY DDS statement. Note: Only the fields that are copied are named fields. Refer to the DDS of this example for comments regarding the DDS used.
- 6
- Format SIGNON is the format with the INVITE keyword. This is the format that will be used to invite devices via the WRITE statement.
- 7
- This is the declaration for the extended file-status MULTIPLE-FS2. It is a 4-byte field that is subdivided into a major return code (first 2 bytes) and a minor return code (last 2 bytes).
- 8
- STATION-ATTR is where the ACCEPT statement stores the attribute data for the TRANSACTION file MULTIPLE-FILE. See item 10 .
- 9
- In this statement, the extended file status MULTIPLE-FS2 is being written.
- 10
- This statement accepts attribute data for the TRANSACTION file MULTIPLE-FILE. Since the FOR phrase is not specified with the ACCEPT statement, the last program device is used.
- 11
- This statement opens the TRANSACTION file MULTIPLE-FILE. Because the ACQPGMDEV parameter of the CRTDSPF command has the value *NONE, no program devices are implicitly acquired when this file is opened.
- 12
- This statement acquires the program device contained in the variable LIST-OF-TERMINALS (COUNTER), for the TRANSACTION file MULTIPLE-FILE.
- 13
- This WRITE statement is inviting the program device specified in the TERMINAL phrase. The format SIGNON has the DDS keyword INVITE associated with it. Refer to item 14 .
- 14
- This READ statement will read from any invited program device. See item 13 . If the wait time expires before anyone inputs to the invited devices, the extended file status will be set to “0310” and processing will continue. See item 15 .
- 15
- In this statement, the extended file status for MULTIPLE-FILE is being checked to see if the wait time expired.
- 16
- The program device name stored in the control area is used to determine which program device was used to sign on. See item 4 .
- 17
- This DROP statement detaches the program device contained in the variable LIST-OF-TERMINALS from the TRANSACTION file MULTIPLE-FILE.