The CLOSE function closes a file.
If windows that were defined for the OPEN still exist, they are disabled using default values for the operands.
The CLOSE function only evaluates the function operands described below.
Format FCT=*CLOSE
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
FCT
Specifies the DIV function to be executed.
= *CLOSE
The CLOSE function closes the file.
Only a direct specification is allowed for the MF=L form.
= addr
Symbolic address of a 1-byte field containing the value for the CLOSE function (field DIVPCLS; see the layout of the parameter list on "DIV function: CLOSE").
= (r)
Register containing the value for the CLOSE function.
ID
Specifies the OPEN for which the CLOSE function is to be executed.
If the same parameter list is used as in OPEN, the ID need not be specified, since the ID of the OPEN will already be in the parameter list. The ID is contained in the DIVPID field of the parameter list.
If a different parameter list is used than the one for OPEN, the ID can be specified here and be transferred to the new parameter list by using the MF=M form of the DIV macro.
ID cannot be specified with the MF=L form.
= addr
Symbolic address of an 8-byte field containing the identification.
= (r)
Register with the address of an 8-byte field containing the identification.
MACID
See the description under the format FCT=*OPEN on "DIV function: OPEN".
MF
The forms of the MF operands are described in detail in the appendix ("Macro types").
PARAM
See the description under the format FCT=*OPEN on "DIV function: OPEN".
PREFIX
See the description under the format FCT=*OPEN on "DIV function: OPEN".
Return codes
Return codes are placed in the header of the parameter list. All DIV-specific return codes are explained in the table below. Other return codes and their meanings as well as the structure of the default header are defined by conventions applicable to all macros and are described on "Standard header".
Standard header: ccbbaaaa
The following code relating to execution of the DIV macro is returned in the standard header (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'cc' | X'bb' | X'aaaa' | Meaning |
X'00' | X'0000' | Function executed successfully. | |
X'01' | X'0001' | At least one part of the parameter list is not accessible. If the header of the parameter list (or a portion thereof) cannot be accessed, or if the parameter list is not aligned on a word boundary, the program will be aborted with an error message. | |
X'01' | X'0002' | The window address specified by AREA (in MAP or UNMAP) is not aligned on a 4K page boundary. | |
X'01' | X'0003' | For MAP, SAVE and RESET: the size of the region (SPAN, possibly in conjunction with the specified OFFSET) results in a disk address that is too large. | |
X'01' | X'0004' | For MAP, SAVE and RESET: | |
X'01' | X'0005' | For MAP: the DISPOS value is neither *OBJECT nor *UNCHNG. | |
X'01' | X'0006' | The value for PFCOUNT is not in the range of 0 to 15 (MAP). | |
X'01' | X'0007' | The value for RELEASE is neither *NO nor *YES (RESET). | |
X'01' | X'0008' | The value for MODE (OPEN) is neither *INPUT, nor *INOUT or *OUTIN. | |
X'01' | X'0009' | The value for SHARUPD (OPEN) is neither *NO, nor *WEAK or *YES. | |
X'01' | X'000A' | The value for LOCVIEW (OPEN) is neither *NONE nor *MAP. | |
X'01' | X'000B' | The value for ENV (OPEN) is neither *HOST nor *XCS. | |
X'01' | X'000C' | The value for LARGE_FILE (OPEN) is neither *ALLOWED nor *FORBIDDEN. | |
X'01' | X'000D' | DIV is not supported on SPARC-HSI. | |
X'40' | X'0014' | DIV calls from TPR are not permitted. | |
X'40' | X'0015' | An error was detected during (general) OPEN handling by DMS. The DIVPDMSC field contains the DMS error code. | |
X'40' | X'0016' | An error was detected during (general) CLOSE handling by DMS. The DIVPDMSC field contains the DMS error code. | |
X'40' | X'0017' | The file is already open. | |
X'40' | X'0018' | The OPEN request is rejected due to one of the following situations:
| |
X'40' | X'0019' | Neither a link name nor a file name is specified (OPEN). | |
X'40' | X'001A' | The file to be opened is located on a shared private disk (SPD). | |
X'40' | X'001B' | A window with the DISPOS=*UNCHNG attribute is not permitted for a file opened with MODE=*INPUT (MAP). | |
X'40' | X'001C' | The privileges of the user (USER or SYSTEM) who opened the file are not the same as those of the user calling the MAP, UNMAP, SAVE, RESET or CLOSE function. | |
X'40' | X'001D' | The ID supplied with one of the functions MAP, UNMAP, RESET or CLOSE to identify the OPEN is not known (any longer) by DIV. | |
X'40' | X'001E' | SPID was specified but does not indicate a data space for the window, or indicates a data space that the caller is not permitted to access (MAP, UNMAP). | |
X'40' | X'001F' | At least part of the address space specified for a window is already being used by an existing window (MAP). | |
X'40' | X'0020' | At least part of the file region specified for a window is already mapped in another window of the opener (MAP). | |
X'40' | X'0021' | SPAN is not specified (or SPAN=0), and cannot be determined by DIV for window definition (MAP) because either
| |
X'40' | X'0022' | The window area contains multiple memory classes (e.g. class 5 and class 6 memory) (MAP). | |
X'40' | X'0023' | A page in the virtual address space has been requested as a window page, but that page has been fixed for an I/O (MAP). | |
X'40' | X'0024' | A page in virtual address space that is intended for a window is resident (MAP). | |
X'40' | X'0025' | A page in virtual address space that is intended for a window is marked READ-ONLY (MAP). | |
X'40' | X'0026' | At least part of the address space that is defined for a window is not allocated (e.g. a REQM was not executed) (MAP). | |
X'40' | X'0027' | The address space specified for a window is shareable (MAP). | |
X'40' | X'0028' | The address space specified for a window is not accessible to nonprivileged users and the caller is not privileged (MAP). | |
X'40' | X'0029' | An internal DIV table cannot be created due to insufficient user address space (MAP). | |
X'40' | X'002A' | The file cannot be physically extended (MAP) because
| |
X'40' | X'002B' | An error occurred when reading a block (MAP, UNMAP). | |
X'40' | X'002C' | An error occurred when writing a block (SAVE). | |
X'40' | X'002D' | The window defined by AREA (and SPID) does not exist for the current OPEN (UNMAP). | |
X'40' | X'002E' | No window exists for the file region defined by OFFSET and SPAN (SAVE, RESET). | |
X'40' | X'002F' | Read-authorized users are not allowed to call SAVE. | |
X'40' | X'0030' | On file access in mode SHARUPD=YES, it was detected that the file size exceeds the value of 32 GB even though there is no permission to exceed this value when using OPEN together with this file. | |
X'80' | X'003C' | The DIV subsystem was stopped by a command. | |
X'80' | X'003E' | The system address space required to create internal DIV tables is not available (OPEN, MAP). | |
X'20' | X'0046' | Internal DIV error. | |
X'20' | X'0047' | Possibly due to an internal DIV error, a wait for the release of a locked system resource was unsuccessful. |
Explanations for the return codes
Return codes are placed in the header of the parameter list:
The main return code is stored in a half-word with the name DIVPMRET.
Subcode1 is stored in a byte with the name DIVPSR1.Subcode1 describes error classes, which allow the caller to respond to them (see table on "Standard header"). The caller can refer both to the main code as well as to subcode1.
Subcode2 is currently not used. It is always zero (X'00').
Return codes cannot be placed in the header if:
the list is not assigned to the user
the list is not aligned on a word boundary
the list is write-protected.
The calling program is aborted with an error message (see section "DMS error codes") and the STXIT event for a “non-recoverable program error” is generated in such cases.
The field names generated by the C or D forms of the macro and EQU instructions for the return codes begin with the string DIVP by default, and can be changed using PREFIX and MACID.
Layout of the parameter list
The following parameter list is returned by a DIV macro with MF=D:
DIV MF=D 1 MFCHK MF=D,PREFIX=D,MACID=IVP,PARAM=, 1 SVC=126,DMACID=IVP,DNAME=IVPLIST,SUPPORT=(C,D,E,L,M) 2 DIVPLIST DSECT , 2 *,##### PREFIX=D, MACID=IVP ##### 1 #INTF REFTYPE=REQUEST,INTNAME=DIV,INTCOMP=002 1 * 1 DIVPPA DS 0F BEGIN of PARAMETERAREA 1 FHDR MF=(C,DIVP),EQUATES=YES 2 DS 0A 2 DIVPFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER 2 * 2 DIVPIFID DS 0A 0 INTERFACE IDENTIFIER 2 DIVPFCTU DS AL2 0 FUNCTION UNIT NUMBER 2 * BIT 15 HEADER FLAG BIT, 2 * MUST BE RESET UNTIL FURTHER NOTICE 2 * BIT 14-12 UNUSED, MUST BE RESET 2 * BIT 11-0 REAL FUNCTION UNIT NUMBER 2 DIVPFCT DS AL1 2 FUNCTION NUMBER 2 DIVPFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER 2 * 2 DIVPRET DS 0A 4 GENERAL RETURN CODE 2 * 2 * GENERAL_RETURN_CODE CLEARED (X'00000000') MEANS 2 * REQUEST SUCCESSFUL PROCESSED AND NO ADDITIONAL INFORMATION 2 * 2 DIVPSRET DS 0AL2 4 SUB RETURN CODE 2 DIVPSR2 DS AL1 4 SUB RETURN CODE 2 2 * ALWAYS CLEARED (X'00') IF MAIN_RETURN_CODE IS X'FFFF' 2 * Standard subcode2 values as defined by convention: 2 DIVPR2OK EQU X'00' All correct, no additional info 2 DIVPR2NA EQU X'01' Successful, no action was necessary 2 DIVPR2WA EQU X'02' Warning, particular situation 2 DIVPSR1 DS AL1 5 SUB RETURN CODE 1 2 * 2 * GENERAL INDICATION OF ERROR CLASSES 2 * 2 * CLASS A X'00' FUNCTION WAS SUCCESSFULLY PROCESSED 2 * CLASS B X'01' - X'1F' PARAMETER SYNTAX ERROR 2 * CLASS C X'20' INTERNAL ERROR IN CALLED FUNCTION 2 * CLASS D X'40' - X'7F' NO CLASS SPECIFIC REACTION POSSIBLE 2 * CLASS E X'80' - X'82' WAIT AND RETRY 2 * 2 DIVPRFSP EQU X'00' FUNCTION SUCCESSFULLY PROCESSED 2 DIVPRPER EQU X'01' PARAMETER SYNTAX ERROR 2 * 3 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'01' - X'1F' 2 DIVPRFNS EQU X'01' CALLED FUNCTION NOT SUPPORTED 2 DIVPRFNA EQU X'02' CALLED FUNCTION NOT AVAILABLE 2 DIVPRVNA EQU X'03' INTERFACE VERSION NOT SUPPORTED 2 * 2 DIVPRAER EQU X'04' ALIGNMENT ERROR 2 DIVPRIER EQU X'20' INTERNAL ERROR 2 DIVPRCAR EQU X'40' CORRECT AND RETRY 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'40' - X'7F' 2 DIVPRECR EQU X'41' SUBSYSTEM (SS) MUST BE CREATED 2 * EXPLICITELY BY CREATE-SS 2 DIVPRECN EQU X'42' SS MUST BE EXPLICITELY CONNECTED 2 * 2 DIVPRWAR EQU X'80' WAIT FOR A SHORT TIME AND RETRY 2 DIVPRWLR EQU X'81' " LONG " 2 DIVPRWUR EQU X'82' WAIT TIME IS UNCALCULABLY LONG 2 * BUT RETRY IS POSSIBLE 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'80' - X'82' 2 DIVPRTNA EQU X'81' SS TEMPORARILY NOT AVAILABLE 2 DIVPRDH EQU X'82' SS IN DELETE / HOLD 2 * 2 DIVPMRET DS 0AL2 6 MAIN RETURN CODE 2 DIVPMR2 DS AL1 6 MAIN RETURN CODE 2 2 DIVPMR1 DS AL1 7 MAIN RETURN CODE 1 2 * 2 * SPECIAL LAYOUT OF LINKAGE_MAIN_RETURN_CODE (YYYY IN X'00XXYYYY') 2 * 2 DIVPRLNK EQU X'FFFF' LINKAGE ERROR / REQ. NOT PROCESSED 2 DIVPFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH 2 * 1 * DIV-FUNCTIONS: 1 DIVPOPEN EQU 1 OPEN 1 DIVPCLS EQU 2 CLOSE 1 DIVPMAP EQU 3 MAP 1 DIVPUNMP EQU 4 UNMAP 1 DIVPSAVE EQU 5 SAVE 1 DIVPRES EQU 6 RESET 1 * DIV-MAINCODES: 1 DIVPPNAC EQU 1 PARLIST NOT ACCESSIBLE 1 DIVPIWAD EQU 2 INVALID WINDOW ADDRESS 1 DIVPISPA EQU 3 INVALID SPAN 1 DIVPIOFF EQU 4 INVALID OFFSET 1 DIVPIDSP EQU 5 INVALID DISPOS 1 DIVPIPFC EQU 6 INVALID PFCOUNT 1 DIVPIREL EQU 7 INVALID RELEASE 1 DIVPIOM EQU 8 INVALID OPEN MODE 1 DIVPISUM EQU 9 INVALID SHARUPD MODE 1 DIVPILVM EQU 10 INVALID LOCVIEW MODE 1 DIVPIENV EQU 11 INVALID LOCKENV 1 DIVPILRF EQU 12 INVALID LARGE_FILE 1 DIVPNSPA EQU 13 DIV NOT SUPPORTED ON SPARC-HSI 1 DIVPPRVC EQU 20 PRIVILEGED DIV CALL 1 DIVPDOER EQU 21 DMS OPEN ERROR 1 DIVPDCER EQU 22 DMS CLOSE ERROR 1 DIVPICOM EQU 23 INCOMPATIBLE OPEN MODE 1 DIVPICFS EQU 24 INCOMPATIBLE FILE SPEC 1 DIVPNLNF EQU 25 NEITHER LINK NOR FILE 1 DIVPPD EQU 26 PRIVATE DISK 1 DIVPDOI EQU 27 DISPOS OPEN INCONSISTENCY 1 DIVPPRVI EQU 28 PRIV INCONSISTENCY 1 DIVPWRID EQU 29 WRONG ID 1 DIVPSIDU EQU 30 SPID UNDEFINED 1 DIVPSPOV EQU 31 SPACE OVERLAP 1 DIVPFOV EQU 32 FILE OVERLAP 1 DIVPUSNP EQU 33 UNDEF SPAN NOT POSSIBLE 1 DIVPINHM EQU 34 INHOMOG MEM 1 DIVPPFIX EQU 35 PAGE FIXED 1 DIVPRESP EQU 36 RESIDENT PAGE 1 DIVPROP EQU 37 READ ONLY PAGE 1 DIVPMNA EQU 38 MEM NOT ALLOC 1 DIVPSHRM EQU 39 SHARABLE MEMORY 1 DIVPPRSP EQU 40 PRIVILEGED SPACE 1 DIVPNOAS EQU 41 NO ADDRESS SPACE 1 DIVPALER EQU 42 ALLOC ERROR 1 DIVPRDER EQU 43 READ ERROR 1 DIVPWRER EQU 44 WRITE ERROR 1 DIVPWNF EQU 45 WINDOW NOT FOUND 1 DIVPNWIR EQU 46 NO WINDOW IN RANGE 1 DIVPSAVN EQU 47 SAVE NOT ALLOWED 1 DIVPLFNS EQU 48 LARGE_FILE NOT SPECIFIED 1 DIVPSSS EQU 60 SUBSYSTEM STOPPED 1 DIVPSOR EQU 61 SHORTAGE OF RESOURCES 1 DIVPIERR EQU 70 INTERNAL ERROR 1 DIVPTOUT EQU 71 TIME RUNOUT 1 * 1 DIVPID DS XL8 ID 1 DIVPLARF DS AL1 LARGE_FILE 1 DIVPFRBD EQU 0 LARGE_FILE=FORBIDDEN 1 DIVPALWD EQU 1 LARGE_FILE=ALLOWED 1 DIVPUNUS DS AL1 UNUSED BYTE 1 DIVPDMSC DS H DMS-CODE 1 DIVPLINK DS CL8 LINK 1 DIVPFILE DS CL54 FILE 1 DIVPOMOD DS AL1 MODE 1 DIVPINPT EQU 1 MODE=INPUT 1 DIVPINOT EQU 2 MODE=INOUT 1 DIVPOUTI EQU 3 MODE=OUTIN 1 DIVPSUPD DS AL1 SHARUPD 1 DIVPSNO EQU 1 SHARUPD=NO 1 DIVPSWEA EQU 2 SHARUPD=WEAK 1 DIVPSYES EQU 3 SHARUPD=YES 1 DIVPLOCV DS AL1 LOCVIEW 1 DIVPLNON EQU 1 LOCVIEW=NONE 1 DIVPLMAP EQU 2 LOCVIEW=MAP 1 DIVPDISP DS AL1 DISPOS 1 DIVPOBJ EQU 1 DISPOS=OBJECT 1 DIVPUNCH EQU 2 DISPOS=UNCHNG 1 DIVPFRSH EQU 3 DISPOS=FRESH 1 DIVPREL DS AL1 RELEASE 1 DIVPRNO EQU 1 RELEASE=NO 1 DIVPRYES EQU 2 RELEASE=YES 1 DIVPLENV DS AL1 LOCKENV 1 DIVPHOST EQU 1 LOCKENV=HOST 1 DIVPXCS EQU 2 LOCKENV=XCS 1 DIVPSIZE DS F SIZE 1 DIVPSPID DS XL8 SPID 1 DIVPAREA DS A AREA 1 DIVPOFFS DS F OFFSET 1 DIVPSPAN DS F SPAN 1 DIVPPFC DS F PFCOUNT 1 DIVP# EQU (*-DIVPPA) LENGTH OF STRUCTURE
Examples
Example 1: Reading and updating an existing file
*-------------------------------------------------------------------*
* Example 1: Reading and updating an existing file *
*-------------------------------------------------------------------*
D1 DIV MF=D
*
BSP001 START
BALR R10,0
USING *,R10
USING D1,R9
LA R9,PA
*-------------------------------------------------------------------*
* Open a file with INOUT *
*-------------------------------------------------------------------*
DIV MF=E,PARAM=PA
CLI DIVPSR1,DIVPRFSP
BNE ERROR
*-------------------------------------------------------------------*
* Determine the file size and request pages for a window. *
* REQM supplies the starting address in R1. *
*-------------------------------------------------------------------*
L R3,DIVPSIZE FILE SIZE IN 4K PAGES -> R3
REQM (R3),PARMOD=31
LTR R15,R15
BNZ ERROR
LR R8,R1
*-------------------------------------------------------------------*
* Create a window in which the pages of the file appear only after *
* an access (DISPOS=*OBJECT and LOCVIEW=*NONE are default settings). *
* A window of the same size as the file is created (OFFSET and SPAN *
* are not specified). *
*-------------------------------------------------------------------*
DIV MF=M,PARAM=PA,FCT=*MAP,AREA=(R8)
DIV MF=E,PARAM=PA
CLI DIVPSR1,DIVPRFSP
BNE ERROR
*-------------------------------------------------------------------*
* Write modified window pages to file. *
*-------------------------------------------------------------------*
DIV MF=M,PARAM=PA,FCT=*SAVE
DIV MF=E,PARAM=PA
CLI DIVPSR1,DIVPRFSP
BNE ERROR
* Disable a window and close the file. *
* After the window is disabled, the pages are in the same state *
* as just before REQM. *
*-------------------------------------------------------------------*
*
DIV MF=M,PARAM=PA,FCT=*UNMAP,DISPOS=*FRESH
DIV MF=E,PARAM=PA
CLI DIVPSR1,DIVPRFSP
BNE ERROR
*
DIV MF=M,PARAM=PA,FCT=*CLOSE
DIV MF=E,PARAM=PA
CLI DIVPSR1,DIVPRFSP
BNE ERROR
*
*
ERROR DS 0Y
*
*
PA DIV MF=L,FCT=*OPEN,LINK='TST001',MODE=*INOUT
END
Example 2: Copying and modifying a file
*-------------------------------------------------------------------*
* Example 2: Copying and modifying a file. *
*-------------------------------------------------------------------*
*
D1 DIV MF=D
*
BSP002 START
BALR R10,0
USING *,R10
USING D1,R9
LA R9,PA1
*-------------------------------------------------------------------*
* Open an existing file. *
*-------------------------------------------------------------------*
DIV MF=E,PARAM=PA1
CLI DIVPSR1,DIVPRFSP
BNE ERROR
*-------------------------------------------------------------------*
* Determine the file size and request pages for a window *
* REQM supplies the starting address in R1. *
*-------------------------------------------------------------------*
L R3,DIVPSIZE FILE SIZE IN 4K PAGES -> R3
REQM (R3),PARMOD=31
LTR R15,R15
BNZ ERROR
LR R8,R1
*-------------------------------------------------------------------*
* Create a window. The pages of the file are immediately read into *
* the window (file pages appear in the window because DISPOS=*OBJECT *
* (default); the pages are read immediately because LOCVIEW=*MAP). *
* A window of the same size as the file is created (OFFSET and SPAN *
* are not specified). *
*-------------------------------------------------------------------*
DIV MF=M,PARAM=PA1,FCT=*MAP,AREA=(R8)
DIV MF=E,PARAM=PA1
CLI DIVPSR1,DIVPRFSP
BNE ERROR
*-------------------------------------------------------------------*
* Modify window pages. *
*-------------------------------------------------------------------*
*
*
*-------------------------------------------------------------------*
* Disable the window and close the file. *
* The contents of the window pages are retained (DISPOS=*UNCHNG). *
*-------------------------------------------------------------------*
*
DIV MF=M,PARAM=PA1,FCT=*UNMAP,DISPOS=*UNCHNG
DIV MF=E,PARAM=PA1
CLI DIVPSR1,DIVPRFSP
BNE ERROR
*
DIV MF=M,PARAM=PA1,FCT=*CLOSE
DIV MF=E,PARAM=PA1
CLI DIVPSR1,DIVPRFSP
BNE ERROR
*
*-------------------------------------------------------------------*
* Open the new file. *
*-------------------------------------------------------------------*
LA R9,PA2
DIV MF=E,PARAM=PA2
CLI DIVPSR1,DIVPRFSP
BNE ERROR
* Create a window. Data remains unchanged (because DISPOS=*UNCHNG). *
* The address of the region is still in R8; the window size in R3. *
*-------------------------------------------------------------------*
DIV MF=M,PARAM=PA2,FCT=*MAP,AREA=(R8),DISPOS=*UNCHNG,SPAN=(R3)
DIV MF=E,PARAM=PA2
CLI DIVPSR1,DIVPRFSP
BNE ERROR
*-------------------------------------------------------------------*
* Write window pages to the new file. *
*-------------------------------------------------------------------*
DIV MF=M,PARAM=PA2,FCT=*SAVE
DIV MF=E,PARAM=PA2
CLI DIVPSR1,DIVPRFSP
BNE ERROR
*-------------------------------------------------------------------*
* Delete the window and close the file. *
*-------------------------------------------------------------------*
DIV MF=M,PARAM=PA2,FCT=*UNMAP,DISPOS=*FRESH
DIV MF=E,PARAM=PA2
CLI DIVPSR1,DIVPRFSP
BNE ERROR
*
DIV MF=M,PARAM=PA2,FCT=*CLOSE
DIV MF=E,PARAM=PA2
CLI DIVPSR1,DIVPRFSP
BNE ERROR
*
*
ERROR DS 0Y
*
*
PA1 DIV MF=L,FCT=*OPEN,LINK='TST001',LOCVIEW=*MAP
PA2 DIV MF=L,FCT=*OPEN,LINK='TST002',MODE=*OUTIN
END