221B CreateFile¶

Validated MON 221B (145 decimal) · Mnemonic CRALF · Group: File Operations (manual section 2.4)

Available from: All programs (manual compatibility box)

Emulation source: src/handlers/mon_221B_CreateFile.c

Description¶

Creates a file. The file may be indexed, contiguous, or allocated. Most files are indexed. The size of indexed files expands automatically when written to. Contiguous and allocated files have shorter access time.

You need directory access to the user who owns the file.
User SYSTEM and RT always have the owner's access rights.
An indexed file not yet written to may be converted to a contiguous file. Use ExpandFile or @EXPAND-FILE.

Parameters¶

Name	Type	Direction	Description
`FileName`	STRING	In	File name. Default file type is :DATA.
`StartAddress`	INTEGER4	In	Start address in the directory. Use 0 if you want to create a contiguous or indexed file.
`NoOfPages`	INTEGER4	In	Length of the file in pages. Use 0 if you want to create an indexed file.

Direction: In = the program supplies the value, Out = the call returns it, In/Out = both.

Compatibility¶

Machines	Users	Programs
ND-100 and ND-500	All users	All programs

The manual's compatibility box for this call, word for word.

Yes/no fields from the YAML extraction (not in the manual's words):

ND-100	ND-500	User programs	RT programs	System programs
Yes	Yes	Yes	Yes	No

Examples¶

From the manual (OCR text, not corrected).

PLANCFORTRANPascalCOBOLASSEMBLY-500MAC

INTEGER4 : StartAddress, NoOfPages
BYTES : FileName(0:63)
...
ON ROUTINEERROR DO
    IF ErrCode > 0 THEN ...
ENDON
Monitor_Call('CreateFile', FileName, StartAddress, NoOfPages)

INTEGER*4 StartAddress, NoofPages
CHARACTER FileName*64
...
Monitor_Call('CreateFile', FileName(1:64), StartAddress, NoofPages)
IF (ErrCode .NE. 0) THEN ...

StartAddress, NoofPages : LONGINT;
FileName : PACKED ARRAY [0..63] OF CHAR;
...
CreateFile(FileName, StartAddress, NoofPages);
IF ErrCode <> 0 THEN ...

01 StartAddress COMP PIC S9(10).
01 NoofPages COMP PIC S9(10).
01 FileName PIC X(64).
01 ErrCode COMP.
...
MONITOR-CALL "CreateFile" USING FileName, StartAddress, NoofPages.
CALL "CbError" USING ErrCode.
IF ErrCode NOT = 0 GO ...

StartAddress : W BLOCK 1
NoOfPages : W BLOCK 1
FileName : STRINGDATA 'EXAMPLE:SYMB'...
ErrCode : W BLOCK 1
CreateFile : EQU 37B9 + 221B
...
CALLG CreateFile, 3, FileName, StartAddress, NoOfPages
IF K GO ERROR
...
ERROR : W1 =: ErrCode        %ErrorCode in W1 register.

LDX  (FILE         %Address of file name string.
LDD  START         %Load register AD with start address.
LDT  (SIZE         %Address of double word with number of pages.
MON  221           %Monitor call CreateFile.
JMP  ERROR         %Error return from monitor call.
...               %Normal return.
ERROR, ...         %Error number in register A.
...
FILE, 'EXAMPLE:SYMB' %Create EXAMPLE:SYMB.
START, ...          %Start address, ie. page address in directory.
...               %A double word.
SIZE, ...           %File size as a double word.
...               %

ndmonlib implementation¶

Validated Registered MON_STATUS_VALIDATED in src/core/mon_registry.c: implemented, tested and working.


Handler	`mon_221B_CreateFile`
Code lines	63 (non-blank, non-comment lines in the file)

Notes from the handler source¶

src/handlers/mon_221B_CreateFile.c line 42

Read filename string from descriptor [Length:4][Pointer:4]
High-level languages (FORTRAN/Pascal) pass string descriptors

src/handlers/mon_221B_CreateFile.c line 66

Translate SINTRAN path to host path
mon_translate_path handles:
- SCRATCH-NNNNN files auto-routed to SCRATCH directory
- Parent directory auto-creation
- Extension from filename (NAME:EXT format)

Emulation research¶

Source

This section comes from the emulation: block of the call's YAML file in the NDInsight repo. It records what was learned while implementing the call in nd500x; its status is nd500x's, not ndmonlib's.


Status (nd500x)	partial
nd500x handler	nd500x/src/libmon/handlers/mon_221B_CreateFile.c
Last updated	2026-07-17

Parameter notes¶

1. FileName

Field	Value
Note	Real callers pass the name as a [Length:4][Pointer:4] string DESCRIPTOR, not inline text; reading the slot directly yields the descriptor struct (first byte 0x00) and so an empty name. nd500x uses mon_read_descriptor_string.
Verified	Yes

2. NoOfPages

Field	Value
Note	1 SINTRAN page = 2048 bytes. When NoOfPages > 0 nd500x pre-allocates NoOfPages*2048 bytes by seeking and writing one byte.
Verified	Yes

Return contract¶

Success: K flag cleared; an empty (or pre-allocated) host file exists.
Errors

Code Octal Meaning

62 076B File already exists

111 157B Missing parameter (no args)

124 174B Illegal parameter (empty file name, or host create failed)

Verified¶

1. An abbreviated name is NOT resolved on create.

Field	Value
Evidence	SINTRAN permits abbreviation only on a READ open; the matcher is hooked in mon_file_table.c only after a literal open fails on a read open, and never here. Commit badb3c4.

Unverified¶

The indexed / contiguous / allocated distinction the manual draws is NOT modelled - every created file is a plain host file. StartAddress is read and logged but has NO effect.
"You need directory access to the user who owns the file" and "an indexed file not yet written to may be converted to a contiguous file" are not modelled - there is no access-rights model behind CreateFile.
The manual's default file type ":DATA" is not applied by the handler; the type comes from the name (NAME:TYPE) or the path translator.
Version handling is not modelled (no new-version-on-create behaviour).

Emulator specific¶

1. SCRATCH-* names are routed to a SCRATCH directory by the path translator, and an EXISTING scratch file is deleted and recreated rather than returning 076B "file already exists". That special case is an emulator decision for the compiler pipeline, not a carved SINTRAN rule.

Field	Value
Evidence	mon_221B_CreateFile.c (is_scratch_file branch).

Discrepancies¶

1. nd500x defaults an OMITTED NoOfPages to 1, pre-allocating 2048 bytes.

Field	Value
Is	Per the manual field ("Use 0 if you want to create an indexed file") the omitted default should be 0 - an indexed file with no pre-allocation. This is an audited-but-NOT-YET-FIXED defect in nd500x, recorded here so the next implementer does not copy it.
Evidence	nd500x/docs/MON_CSHARP_SYNC_HANDOFF.md Part C ("221B CreateFile: omitted NoOfPages should default to 0 (indexed, no prealloc), not 1") and MON_COMPLETENESS_MATRIX.md row 221B (PARTIAL).

Sources¶

Doc	Note	Commit
SINTRAN III Monitor Calls (ND-860228.2 EN)	The manual page this YAML was extracted from.
nd500x/docs/MON_CSHARP_SYNC_HANDOFF.md	Part C - the NoOfPages default defect.
		6b57202 (nd500x) - real SINTRAN error codes (file already exists = 62 / 076B)

Source¶

SINTRAN III Monitor Calls (ND-860228.2 EN), page 125.

Code	Octal	Meaning
62	076B	File already exists
111	157B	Missing parameter (no args)
124	174B	Illegal parameter (empty file name, or host create failed)