SYS$ – SYS$ Interface Routines

The callable surface

The SYS$ module itself exports more than 110 system-service entry points. A migrated application, however, sees a wider callable surface of over 150 SYS$ routines, because the file and record services and the lock-manager services are provided by sibling modules linked from the same runtime. Those siblings are documented on their own pages: the RMS-shaped services such as SYS$OPEN, SYS$READ, and SYS$CONNECT live in VX/RMS, and the lock services SYS$ENQ, SYS$DEQ, and SYS$GETLKI live in VX/LCKMGR. This page covers the system-service routines implemented in the SYS$ module itself.

Layering

The runtime sits between the unchanged application and the host operating system:

The queued I/O driver subsystem

The I/O services are not a flat call table. SYS$QIO and SYS$QIOW validate the channel, then forward to an inner executive worker that routes the request to a per-device-class driver. Each driver is compiled into libvxrt.a and runs on a dedicated POSIX thread, with ASTs delivered by queuing onto the per-process AST dispatcher.

A shared support layer and the driver-thread module provide the asynchronous plumbing behind the whole QIO family, so a queued read or write behaves as it did on VMS regardless of the underlying host device.

Cross-language re-aliases

A small set of routines carry extra prefixes for callers generated in other languages:

• COB$xxxx re-exports let generated COBOL issue CALL "COB$xxxx". These are identical wrappers of their SYS$ counterparts, covering information and job-control services such as COB$GETJPI, COB$GETSYI, COB$SNDJBC, and COB$TRNLNM.
• EXE$xxxx exports expose the inner executive workers directly. Unlike the COBOL re-aliases, these are not identical wrappers: the SYS$ form wraps the inner worker in the runtime trace scope, while the EXE$ form is the bare inner call. The routines with both forms are CANCEL, GETQUI, GETTIM, QIO, and SYNCH.

Device, resource, and channel management

Process control and ASTs

Memory and virtual address space

Event flags, timers, and synchronization

Time and format conversion

Information services

Logical names, messaging, and job control

Privilege and security

String descriptors

All character arguments use the same VMS descriptor model as the STR$ library, in both 32-bit and 64-bit forms, classified automatically at the call. The same descriptor helpers extract or build a descriptor regardless of width, so a routine accepts whichever form the caller passes. The shared descriptor model is documented on STR$ String Interface Routines.

Item lists

The information services and several others take a zero-terminated item-list array. Both the 32-bit and 64-bit item-list layouts are accepted and detected per element:

struct ITL {                   // 32-bit form
    union {
        struct { short Length; short Code; } Item;
        long terminator;       // zero longword ends the list
    } u;
    void  *Address;            // buffer for the item value
    short *Length_Ptr;         // OUT: actual returned length
};

Outputs are stored only when the caller supplies a non-NULL pointer, matching the OpenVMS convention that optional return arguments may be omitted.

Status codes and the return model

Every service returns a 32-bit VMS condition value. VX/SYS$ returns the same SS$_XXX symbols and preserves the VMS severity convention: a successful status is odd, a failure is even, so existing ODD(status) tests behave exactly as they did on VMS. A representative set of the codes the system services use most:

Most services return the condition value directly. A small number additionally raise conditions as VMS-style signals, catchable with the usual condition-handler establishment or a C++ handler, so code that relies on signalled conditions still works.

Tracing scaffold

Every routine opens with a trace-entry marker and returns through a matching trace-exit marker, so per-thread entry and exit records feed the runtime debug logger. The instrumentation is uniform across the whole service set, which makes a migrated application straightforward to trace end to end during cut-over.

Deliberate divergences from native OpenVMS

These are behaviours that differ by design because the host is Linux rather than OpenVMS:

• Privilege checks are advisory. Obvious cases return SS$_NOPRIV, but most services do not enforce the full SOGW protection mask the way VMS does.
• Quotas are not enforced. An exceeded-quota status is documented as possible but is essentially never produced.
• Clustering is absent. Node arguments are accepted but everything resolves to the local node; wildcard scans end with the no-more-nodes status.
• ASTs run on a dedicated thread. ASTs are serialized on a per-process dispatcher and cannot pre-empt CPU-bound mainline code without an explicit cancellation point, so code that relies on AST pre-emption sees different scheduling.
• Process IDs are not host PIDs. Use SYS$GETJPI to read the VMS process identifiers rather than assuming they match the host operating-system process IDs.
• The exit-status convention is preserved. SYS$EXIT follows the VMS low-bit rule, where an even code signals failure and an odd code signals success, which can surprise callers new to VMS.
• Access-mode arguments are ignored. An access-mode argument is accepted for prototype compatibility but not honoured, since the host has no VMS access-mode model.

Representative SYS$ services

Name forms and status codes

Queue, wait, and release skeleton

A migrated program links this unchanged against libvxrt.a. Note the ODD() status test after each call and the event-flag synchronization after the queued write:

// timestamp and queue a write to the funds-transfer journal device
status = SYS$GETTIM(&now);                       // current system time, 100 ns units
if (!ODD(status)) goto fail;

status = SYS$ASSIGN("BANKING$JOURNAL", &chan, 0, 0);
if (!ODD(status)) goto fail;

status = SYS$QIOW(efn, chan, IO$_WRITEVBLK,      // queue the write and wait for completion
                  &iosb, 0, 0,
                  record, record_len, 0, 0, 0, 0);
if (!ODD(status)) goto fail;

SYS$DASSGN(chan);                                // release the channel

Related pages

• VX/RT APIs for the runtime ecosystem that hosts VX/SYS$.
• EXE$ Operating System Interface for the inner executive workers that the system services wrap.
• VX/RMS SYS$ Routines for RMS for the record and file services behind open, close, read, and write.
• VX/LCKMGR for the lock and enqueue services behind SYS$ENQ, SYS$DEQ, and SYS$GETLKI.
• STR$ String Interface Routines and LIB$ General Routines for the run-time-library companions in the same collection.