The File Communication Block (FCB)

In this section: FCB Area Layout Using Both Local and Centrally Controlled Databases Error Codes

All HLI commands start with the command name as the first argument in the call, followed by the File Communication Block (FCB) as the second argument. For example:

CALL FOCUS ('OPN ',MYFCB) 

The FCB is always 200 bytes with a fixed layout. The user program supplies some of the parameters in the FCB, such as the CMS fileid (filename, filetype, and filemode) of the database. HLI fills in the other parameters, such as the status return code.

When running a program under SU, place the value SU in FCB word 6. (Note: Two blanks must follow the characters "SU".) Place the user ID of the virtual machine that will process the HLI calls (the sink machine) in FCB words 9 and 10. These are the only changes you must make to your HLI programs to have them run under SU.

FCB Area Layout

FCB Words	Item	Meaning	Bytes Used
1-2	FN	CMS and FOCUS filename of database (or HLI control command)	8
3-4	FT	CMS filetype of database	8
5	FM	CMS filemode of database (padded with two trailing blanks)	4
6	SU	Can be either: SU (SU followed by two blanks) or four blanks	4
7-8	PROCNAME	Displayed on HLIPRINT	8
9-10	SINKID	User ID of sink machine	8
11-12	-	Reserved	8
13-15	-	Reserved	12
16-17	BACKKEY	Address key of target segment	8
18	ECHO	ECHO or STAT	4
19-20	PASSCTL	File access password	8
21-22	NEWSEG	Name of highest new segment retrieved	8
23	SEGNUM	Segment number of NEWSEG (integer)	4
24	STATUS	Status return code (integer)	4
25	ERRORNUM	Detail error code (integer)	4
26-32	-	Reserved	28
33	SHOLENGTH	Length of one record returned	4
34	LENGTH	Length of work area returned	4
35-50	-	Reserved	64

Note that the HLI program can place information useful for debugging in words 7 and 8 of the FCB. This information is displayed on the HLIPRINT trace in the PROCNAME column.

Using Both Local and Centrally Controlled Databases

A single program can use a combination of centrally controlled databases and local FOCUS files. Whenever the program is using the centrally controlled databases, the FCB must have the characters SU_ _ in word 6 and the sink machine user ID in words 9 and 10. Under HLI, each open file must have its own FCB.

Error Codes

After every HLI call is executed, a status code is placed in the File Communication Block (FCB) word 24, shared by the host program and HLI. A status code of 0 means that the command executed correctly. A status code of 1 means that the command executed correctly, but no more data of the type requested was available. All higher numbered status codes indicate error conditions such as incorrect field names or missing parameters. A list of status codes is provided in HLI Status Codes Returned in FCB Word 24.

If you are modifying the database using the INP, CHA, and DEL commands, and another user is trying to modify the same segment instance at the same time, your transaction may be rejected because the other user's transaction was accepted first (this process is explained in Introduction). If this happens, your FCB receives one of the following status codes:

784

You attempted to add a new segment instance. Your transaction was rejected, because another user added the same segment instance first. (Analogous to FOCURRENT=1 in MODIFY/SU).

786

You attempted to update or delete a segment instance. Your transaction was rejected, because another user deleted the instance first. (Analogous to FOCURRENT=2 in MODIFY/SU).

789

You attempted to update or delete a segment instance. Your transaction was rejected, because another user updated the instance first. (Analogous to FOCURRENT=3 in MODIFY/SU).

If word 24 is a non-zero value, FCB word 25 may contain the detail error code. Word 25 indicates an IUCV error, which is a subcategory of the error specified by the status code in FCB word 24. If word 25 is not 0, record the code and contact your Information Builders representative.

Note: Status code 802, detail error code 5, indicates the sink machine terminated abnormally.