extlink_np (BPX1EXT, BPX4EXT) — Create an external symbolic link

Function

The extlink_np service creates a symbolic link to an external name. A file named Link_name, of type "symbolic link" is created. The content of the symbolic link file is the external name specified in Ext_name.

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1EXT): 31-bit
AMODE (BPX4EXT): 64-bit
ASC mode: Primary mode
Interrupt status: Enabled for interrupts
Locks: Unlocked
Control parameters: All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1EXT,(Ext_name_length,
              Ext_name,
              Link_name_length,
              Link_name,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4EXT with the same parameters.

Parameters

Ext_name_length
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword containing the length of Ext_name. The Ext_name can be up to 1023 bytes long.

Ext_name
Supplied parameter
Type:
Character string
Character set:
No restriction
Length:
Specified by the Ext_name_length parameter

The name of a field containing the external name for which you are creating a symbolic link. An external name is the name of an object outside the hierarchical file system.

Link_name_length
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword containing the length of Link_name. The Link_name can be up to 1023 bytes long; each component of the name (between delimiters) can be up to 255 bytes long.

Link_name
Supplied parameter
Type:
Character string
Character set:
No restriction
Length:
Specified by Link_name_length parameter

The name of a field containing the symbolic link being created.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword where the extlink_np service returns 0 if the request is successful, or -1 if it is not successful.

Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the extlink_np service stores the return code. The extlink_np service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The extlink_np service can return one of the following values in the Return_code parameter:
Return_code Explanation
EACCES The calling process does not have permission to search a directory in the Link_name, or does not have permission to write in the directory to contain the symbolic link file.
EEXIST Link_name already exists.
EINVAL Parameter error. Possible reasons are:
  • Ext_name_length exceeds the maximum allowed.
  • Ext_name_length is zero.
  • Link_name has a slash as its last component, which indicates that the preceding component is a directory. A symbolic link cannot be a directory.

    The following reason codes can accompany the return code: JRInvalidSymLinkLen, JREndingSlashSymLink.
ELOOP A loop exists in symbolic links encountered during resolution of the Link_name argument. This error is issued if more than 24 symbolic links are detected in the resolution of Link_name.
ENAMETOOLONG Link_name is longer than 1023 characters, or some component of that name is longer than 255 characters. Name truncation is not supported.
ENOSPC The directory in which the entry for the symbolic link is being placed cannot be extended; not enough space remains in the file system.
ENOTDIR A component of the path prefix of Link_name is not a directory.
EROFS The requested operation requires writing in a directory on a read-only file system.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword where the extlink_np service stores the reason code. The extlink_np service returns a Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

  1. The extlink_np service creates an external symbolic link (Link_name) with the object you specify by Ext_name.
  2. The object identified by Ext_name need not exist when the symbolic link is created, and refers to an object outside a hierarchical file system.
  3. The external name contained in an external symbolic link is not resolved. The Link_name cannot be used as a directory component of a pathname.

Related services

Characteristics and restrictions

None.

Examples

For an example using this callable service, see BPX1EXT (extlink_np) example.

Parent topic: Callable services descriptions