Synopsis

pointer = ALLOCMEM(size[, attributes])

Function

Allocates memory using Exec AllocMem(). Returns the allocated address
as a binary pointer value in a Rexx argument string.

Inputs

size       - Allocation size expressed as a decimal string.
attributes - Optional four-byte binary Exec memory attribute mask.
             If omitted, MEMF_PUBLIC is used. Byte 0 supplies bits
             31-24; byte 3 supplies bits 7-0.

Result

A pointer-sized binary argument string on success. ERR10_018 is returned
for an invalid size string or attribute length, and ERR10_003 if Exec
allocation fails.

Notes

The result is binary pointer data, not a printable decimal address.
The caller must eventually pass the same pointer and allocation size to
FREEMEM(). The pointer size depends on the target architecture.

Bugs

If memory allocation succeeds but creation of the result argument
string fails, the function does not release the allocated memory.

See also

FREEMEM NULL OFFSET

Synopsis

ULONG ArexxDispatch(struct RexxMsg *msg, STRPTR *_retargstringptr);

Function

Dispatches a RexxSupport library query to a named script function.
Matches the name in rm_Args[0], checks the argument count encoded in
rm_Action, and invokes the corresponding handler.

Inputs

msg               - Rexx message containing the requested function
                    name and its argument strings.
_retargstringptr  - Receives the result argument-string pointer, or
                    NULL if the query does not produce a value.

Result

Handler status on a known function with valid argument count; 1 for
an unknown name; ERR10_018 for an unsupported argument count.

Notes

This is the RexxSupport query entry point used by the Rexx runtime,
not a general-purpose C function-call interface. Non-NULL result
strings are Rexx argument strings managed by the message protocol.

See also

rexxsyslib.library/CreateArgstring()

Synopsis

pointer = BADDR(bptr)

Function

Converts a binary BPTR value into a native C address using BADDR().

Inputs

bptr - A binary argument string containing exactly sizeof(void *)
       bytes representing a BPTR value.

Result

A binary argument string containing a native pointer. ERR10_018 is
returned when the input is not pointer-sized.

Notes

The result is binary address data and is not a character string.
The function does not verify that the resulting address is valid.

See also

NULL OFFSET

Synopsis

result = CLOSEPORT(name)

Function

Unregisters a named message port previously opened by RexxSupport in
the current library instance. Replies to pending messages during cleanup.

Inputs

name - Name of the managed message port to close.

Result

The string "1" if a managed port was found and closed, or "0" if
not found. ERR10_013 indicates a missing REXX port; ERR10_003 denotes
a failure to allocate the registration message or reply port.

Notes

Only ports managed by RexxSupport are eligible. Port registration is
coordinated with RexxMast before cleanup.

Bugs

The implementation does not validate all intermediate allocation
results before using them.

See also

OPENPORT WAITPKT GETPKT REPLY

Synopsis

VOID ClosePortRsrc(
         struct RexxRsrc * rsrc );

Function

Removes and releases a RexxSupport-managed message port resource.
Returns outstanding tracked or queued messages to their senders,
then releases the port and its tracking structures.

Inputs

rsrc - Pointer to a RexxRsrc embedded in a PortNode registered by
       RexxSupport. It must refer to a live managed resource.

Result

None.

Notes

This cleanup entry point is used for resource disposal. It must not
be passed an unrelated RexxRsrc or an arbitrary RexxMsg pointer.

See also

CLOSEPORT

Synopsis

result = DELAY(ticks)

Function

Suspends the calling task for the specified number of DOS ticks.

Inputs

ticks - Nonempty decimal string containing only digits.

Result

The string "0" after Delay() returns. Invalid input produces
ERR10_018.

Notes

A DOS tick is the unit accepted by DOS Delay(); this function does
not accept a duration in milliseconds.

See also

FORBID PERMIT

Synopsis

result = DELETE(path)

Function

Deletes a file or filesystem entry using DOS DeleteFile().

Inputs

path - Path of the entry to delete.

Result

The string "1" if DeleteFile() succeeds, or "0" if it fails.

Notes

A failed deletion is represented by the returned string, not by a
nonzero RexxSupport dispatch status.

See also

MAKEDIR RENAME

Synopsis

nesting = FORBID()

Function

Requests a nested task-switching prohibition through Exec Forbid().

Result

A decimal nesting count represented as a string. ERR10_012 is
returned if the script nesting variable cannot be updated.

Notes

Match each successful FORBID() with PERMIT(). Avoid operations that
wait for other tasks while task switching is prohibited.

Bugs

The implementation also uses static process-wide nesting state;
concurrent or unrelated script invocations do not have independent
in-memory nesting counters.

See also

PERMIT

Synopsis

success = FREEMEM(pointer, size)

Function

Releases an Exec memory allocation using FreeMem().

Inputs

pointer - Binary pointer argument string containing exactly
          sizeof(void *) bytes, as returned by ALLOCMEM().
size    - Decimal allocation size supplied to the matching ALLOCMEM().

Result

The string "1" after FreeMem() is called. An invalid pointer-string
length or size representation produces ERR10_018.

Notes

The allocation must still be live, and size must match its original
allocation. Do not use the address after the call.

See also

ALLOCMEM

Synopsis

value = GETARG(message[, index])

Function

Copies one Rexx argument from a message identified by its binary
pointer value into a new Rexx argument string.

Inputs

message - Binary pointer to a RexxMsg, as returned by GETPKT().
index   - Optional argument index; when omitted, index 0 is selected.

Result

An allocated argument string on success. ERR10_018 is returned for
an invalid message identity or invalid parsed index.

Notes

The message must remain valid until this call completes. Argument
indices refer to the rm_Args array, beginning at zero.

Bugs

When index is supplied, the implementation incorrectly parses the
binary message pointer argument as a decimal index instead of parsing
the second argument. It also does not validate the pointer argument's
byte length before dereferencing it.

See also

GETPKT TYPEPKT REPLY

Synopsis

message = GETPKT(port)

Function

Removes the next message from a RexxSupport-managed message port and
tracks it for a later REPLY().

Inputs

port - Name of a port previously created with OPENPORT().

Result

A binary argument string containing a native message pointer.
ERR10_018 is returned when the port is not managed by RexxSupport.

Notes

Call WAITPKT() to wait until a message is present before using GETPKT().
The result contains binary pointer data, not printable text.

Bugs

The implementation does not check whether GetMsg() returned NULL
before adding the pointer to its internal message list.

See also

OPENPORT WAITPKT GETARG REPLY

Synopsis

result = MAKEDIR(path)

Function

Creates a directory using DOS CreateDir().

Inputs

path - Path of the directory to create.

Result

The string "1" if CreateDir() succeeds, or "0" otherwise.

Notes

The temporary directory lock is released before the function returns.

See also

DELETE RENAME

Synopsis

value = NEXT(pointer[, offset])

Function

Copies a pointer-sized sequence of bytes from the supplied argument
string's own data buffer, starting at the specified byte offset.

Inputs

pointer - Binary argument string of exactly sizeof(void *) bytes.
offset  - Optional signed decimal byte offset; defaults to zero.

Result

A pointer-sized binary argument string. ERR10_018 is returned for
an invalid pointer-string length or offset representation.

Bugs

Despite its name, the implementation does not dereference the pointer
encoded in pointer. A nonzero offset is not checked against the input
buffer size and can read outside the argument string.

See also

OFFSET BADDR

Synopsis

pointer = NULL()

Function

Returns a binary representation of a native null pointer.

Result

An argument string containing sizeof(void *) zero-valued pointer
bytes. This is not the printable string "0".

See also

ALLOCMEM BADDR OFFSET

Synopsis

pointer = OFFSET(pointer, displacement)

Function

Adds a signed byte displacement to a pointer value and returns the
resulting address in binary form.

Inputs

pointer      - Pointer-sized binary argument string.
displacement - Signed decimal byte offset.

Result

Pointer-sized binary argument string containing the adjusted address.
ERR10_018 is returned for an invalid input length or offset string.

Notes

The function performs pointer arithmetic only; it does not check the
adjusted address or access the memory it designates.

See also

ALLOCMEM NEXT BADDR

Synopsis

result = OPENPORT(name)

Function

Creates a named Exec message port and registers its ownership with
the REXX message service for cleanup when the script finishes.

Inputs

name - Requested public message-port name.

Result

The string "1" if a port was created and the registration exchange
completed, or "0" if the name is already in use or port creation
fails. ERR10_013 indicates that the REXX port is unavailable;
ERR10_003 indicates allocation failure during setup.

Notes

The call waits for a reply to its resource-registration message.
Close a successfully created port with CLOSEPORT() when finished.

Bugs

The implementation does not check every allocation result and
can retain a partially created port when setup fails. It logs but
does not propagate a failed RexxMast registration response.

See also

CLOSEPORT WAITPKT GETPKT

Synopsis

nesting = PERMIT()

Function

Releases one nesting level of the task-switching prohibition managed
by RexxSupport, invoking Exec Permit() when its active level ends.

Result

A decimal nesting count represented as a string. ERR10_012 is
returned if the script nesting variable cannot be updated.

Notes

Call PERMIT() once for each corresponding FORBID().

Bugs

The implementation relies partly on static process-wide state, so
unrelated script executions are not independently tracked.

See also

FORBID

Synopsis

result = RENAME(oldname, newname)

Function

Renames or moves a filesystem entry using DOS Rename().

Inputs

oldname - Current path of the entry.
newname - Requested new path.

Result

The string "1" if Rename() succeeds, or "0" if it fails.

See also

DELETE MAKEDIR

Synopsis

result = REPLY(message[, code])

Function

Removes a received message from RexxSupport's tracking list and sends
an Exec reply to its reply port.

Inputs

message - Binary pointer to a message obtained using GETPKT().
code    - Optional intended Rexx return code for a RexxMsg.

Result

The string "1" after sending the reply. ERR10_018 is returned if
the decoded message pointer is NULL or the parsed code is invalid.

Notes

After REPLY(), do not use the message pointer; ownership has passed
back to the original sender.

Bugs

When code is supplied, the implementation parses the binary message
pointer argument instead of the second argument. It does not validate
the pointer argument's byte length or membership in the tracked list.

See also

GETPKT GETARG TYPEPKT

Synopsis

entries = SHOWDIR(path[, type[, separator]])

Function

Lists the names of entries in a directory, optionally filtering
entries by filesystem type.

Inputs

path      - Directory to enumerate.
type      - Optional filter: A for all entries, F for files, or D for
            directories; only the first letter is interpreted.
separator - Optional string whose first character separates names;
            the default separator is a space.

Result

An argument string containing separated names, or an empty string
when the path cannot be opened or does not name a directory.
ERR10_018 is returned for an unrecognized type selector.

Notes

The names are not individually escaped or quoted. A separator that
occurs in a filename makes the output ambiguous.

Bugs

A NULL third argument is dereferenced because the separator check
uses an incorrect condition. The ExAll() loop tests its return value
in the opposite sense to its documented completion convention and
may fail to terminate. Some failure paths retain a DOS lock;
allocation failures are not consistently handled.

See also

SHOWLIST STATEF

Synopsis

result = SHOWLIST(kind[, name[, separator]])

Function

Lists or searches a selected system list. Without name, returns list
member names separated by separator. With name, tests for membership.

Inputs

kind      - First letter chooses A (assigns), D (Exec devices),
            H (DOS devices), I (interrupts), L (libraries),
            M (memory headers), P (ports), R (resources),
            S (semaphores), T (ready tasks), V (volumes), or
            W (waiting tasks).
name      - Optional name to test rather than listing all entries.
separator - Optional separator string; its first byte is used.
            Defaults to one space.

Result

With no name, a separated list of names. With name, "1" if a
match is found or "0" otherwise. Invalid kind returns ERR10_018.

Notes

Exec-list names use exact string comparison. DOS-list name matching
uses a length-limited prefix comparison in this implementation.

Bugs

Some branches assume successful memory allocation and non-NULL
list-entry names. Result strings are not escaped for separators.

See also

SHOWDIR STATEF

Synopsis

state = STATEF(path)

Function

Returns filesystem information for a path as a space-separated
sequence of textual fields.

Inputs

path - Filesystem path to examine.

Result

The fields are type (FILE or DIR), size in bytes, block count,
eight protection characters (H, S, P, A, R, W, E, D, or '-'),
followed by datestamp days, minutes, and ticks. An inaccessible
path produces an empty string. Allocation failure for the file
information block produces ERR10_003.

Notes

The protection letters correspond to the FileInfoBlock flags;
read, write, execute, and delete bits use the DOS inhibit polarity.

Bugs

The implementation does not release the filesystem lock, and it
does not consistently check other allocations or Examine() results.

See also

SHOWDIR SHOWLIST

Synopsis

result = TYPEPKT(message[, selector])

Function

Reads the action code from a Rexx message obtained through a
binary message pointer.

Inputs

message  - Pointer-sized binary argument string naming a RexxMsg.
selector - Optional selector: A for argument count, C to test RXCOMM,
           or F to test RXFUNC. The first character is used.

Result

Without selector, a binary LONG containing rm_Action. With A,
a single ASCII digit for the argument count. With C or F,
the string "1" when the action matches or "0" otherwise.

Bugs

No message-pointer validation is performed. Unrecognized selectors
leave the single-byte result uninitialized.

See also

GETPKT GETARG REPLY

Synopsis

result = WAITPKT(port)

Function

Waits until at least one message is available at a RexxSupport-
managed message port.

Inputs

port - Name of a port created by OPENPORT().

Result

The string "1" when WaitPort() returns. Unknown port names
produce ERR10_018.

Notes

WAITPKT() does not remove a message from the port. Call GETPKT()
afterward to retrieve it.

See also

OPENPORT GETPKT REPLY