Start NetWare Connection (QfpzStrNtwCnn) API

Required Parameter Group:

1	Connection data	Input	Char(*)
2	Length of connection data	Input	Binary(4)
3	Connection data format name	Input	Char(8)
4	Error code	I/O	Char(*)

  Default Public Authority: *USE

  Library Name/Service Program: QFPNTWE/QFPZAAPI

  Threadsafe: No

The Start NetWare Connection (QfpzStrNtwCnn) API establishes the caller as an authenticated user of the specified server. This API could be used to:

Start a connection to a server for which a user has no authentication entry
Start a connection when the authentication entry has the password special value *STRNTWCNN
An authentication entry may have the value *STRNTWCNN because the QRETSVRSEC system value does not allow retrieving security data such as passwords.
Start a connection to a server by using a different NetWare user name than is specified in the authentication entry for that server

If an authentication entry for the server exists and contains a valid password and user name, the system starts a connection to the server when needed, and this API need not be used.

Connections may only be used by the specified user and job. The job may be either the current job (value 1 for the authorized job field) or any job (value 2 for the authorized job field) on the system. If any job is specified, all jobs that are running under the specified user profile can use the connection. If a connection for a user profile and job exists, that connection is used. Otherwise, an any-job connection for the user profile is used. A current-job connection might be used, for example, when a job uses a connection with a different NetWare user name than other jobs on the system. An any-job connection is required for certain functions, for example, printing to a NetWare print server.

NetWare backup services require a separate authentication. To support this, the connection type field specifies whether a normal login (*USER connection) or a backup services authentication (*SAVRST connection) is to be performed.

A user profile can only have one connection per job to a server (either NetWare 3.x server or a server within a NetWare Directory Services (NDS) tree) at any given time. Connections may be started to all servers within an NDS tree, for example, when copying from one server to another. If connections to multiple servers are open, operations that do not require a specific server use the first connection started.

Authorities and Locks

User Profile Authority: *USE

Required Parameter Group

Connection data

INPUT; CHAR(*)

The server and user name for the connection to be started. The content and format of this structure are determined by the format name. See Format of Connection Data for a description of these formats.

Length of connection data

INPUT; BINARY(4)

The length of the connection data structure.

Connection data format name

INPUT; CHAR(8)

The content and format of the input data. Several formats are provided. Each format corresponds to a type of server.

The possible format names follow:

SVRC0100	Start a connection to a NetWare Version 3.x server.
SVRC0200	Start a connection to a server in a NetWare Directory Services tree.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format of Connection Data

For details about the format of the connection data, see the following sections. For details about the fields in each format, see Field Descriptions.

SVRC0100 Format (NetWare Version 3.x Server)

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Offset to server name
0	0	BINARY(4)	Offset to server name
4	4	BINARY(4)	Length of server name
8	8	BINARY(4)	Offset to NetWare user name
12	C	BINARY(4)	Length of NetWare user name
16	10	BINARY(4)	Offset to password
20	14	BINARY(4)	Length of password
24	18	BINARY(4)	Offset to connection type list
28	1C	BINARY(4)	Number of entries in connection type list
32	20	BINARY(4)	Authorized job
36	24	BINARY(4)	Connection idle time
40	28	CHAR(10)	User profile name
50	32	CHAR(6)	Reserved
		CHAR(*)	Server name
		CHAR(*)	NetWare user name
		CHAR(*)	Password
Note: The following field is repeated for each connection type requested.
		BINARY(4)	Connection type

SVRC0200 Format (NetWare Directory Services Tree)

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Offset to NDS tree name
4	4	BINARY(4)	Length of NDS tree name
8	8	BINARY(4)	Offset to server name
12	C	BINARY(4)	Length of server name
16	10	BINARY(4)	Offset to NDS context
20	14	BINARY(4)	Length of NDS context
24	18	BINARY(4)	Offset to NetWare user name
28	1C	BINARY(4)	Length of NetWare user name
32	20	BINARY(4)	Offset to password
36	24	BINARY(4)	Length of password
40	28	BINARY(4)	Offset to connection type list
44	2C	BINARY(4)	Number of entries in connection type list
48	30	BINARY(4)	Authorized job
52	34	BINARY(4)	Connection idle time
56	38	CHAR(10)	User profile name
66	42	CHAR(6)	Reserved
		CHAR(*)	NDS tree name
		CHAR(*)	Server name
		CHAR(*)	NDS context
		CHAR(*)	NetWare user name
		CHAR(*)	Password
Note: The following field is repeated for each connection type requested.
		BINARY(4)	Connection type

Field Descriptions

Authorized job. The jobs authorized to use the connection.

The following values may be specified:

1	The connection can be used only by the current job. The connection ends when the current job is ended, or when the connection is ended by an end NetWare connection request.
2	The connection can be used by any job on the system that is running under the specified user profile. The connection must be explicitly ended by an end NetWare connection request.

Notes:

The QNETWARE file system requires a connection for the current job.
If no authentication entry exists, or the password in the authentication entry is *STRNTWCNN, printing functions require that a connection for any job (authorized job value is 2) be started.
If the authorized job value is 1 and user reclaims the QFPZAUT activation group (RCLACTGRP command), the connection ends.
For either authorized job value, you may use the connection idle time value to control when a connection ends.

Connection idle time. The idle time (in minutes) before a connection is closed by the system. Idle time is the time between subsequent requests. Valid values range from 1 minute through 9999 minutes.

The following special value may be specified:

-1	There is no idle time. A connection is closed by the user, or it is closed when the job has ended (if the authorized job value is 1).

Connection type. The type of authentication to be performed. NetWare backup services require a separate authentication in addition to a normal user authentication.

The following values may be specified:

1	A normal user authentication is done. The user can use administrative and file system functions other than save and restore.
2	Authentication to NetWare backup services is performed. This option requires that the appropriate NetWare Loadable Module software (TSA312.NLM, TSA410.NLM, or TSANDS.NLM, and SMDR.NLM) be loaded on the server.
-1	Perform both user and backup services authentications. If -1 is specified, it must be the only connection type value specified.

Length of NDS context. The length, in bytes, of the NDS context.

Length of NDS tree name. The length, in bytes, of the NDS tree name.

Length of NetWare user name. The length, in bytes, of the NetWare user name.

Length of password. The length, in bytes, of the password.

Length of server name. The length, in bytes, of the server name.

NDS context. For NetWare Directory Services trees, the directory context in which the user is defined.

The following special value may be used:

*AUTE

Use the NDS context from the user profile authentication entry for this NDS tree.

NDS tree name. The name of the NetWare Directory Services tree to which the connection is to be started.

NetWare user name. The NetWare user name that is used to authenticate the user to the server.

The following special values may be used:

*USRPRF	Use the authorized i5/OS user profile name as the NetWare user name.
*AUTE	Use the NetWare user name from the user profile authentication entry for this server or NDS tree.

Number of entries in connection type list. The number of connection type values in the connection type list. At least one value must be specified.

Offset to connection type list. The offset, in bytes, from the start of the data area to the connection type values.

Offset to NDS context. The offset, in bytes, from the start of the data area to the NDS context.

Offset to NDS tree name. The offset, in bytes, from the start of the data area to the NDS tree name.

Offset to NetWare user name. The offset, in bytes, from the start of the data area to the NetWare user name.

Offset to password. The offset, in bytes, from the start of the data area to the password.

Offset to server name. The offset, in bytes, from the start of the data area to the server name.

Password. The password that is used to authenticate the user to the server.

The following special values may be used:

*AUTE	Use the password from the user profile authentication entry for this server or NDS tree.
*NONE	No password is used to authenticate the user.

Reserved. Set this field to binary zeros.

Server name. The name of the server to which the connection is to be started.

When you are connecting to a NetWare Version 3.x server, the server name must be specified.

When you are connecting to a NetWare Directory Services tree, the connection must be started on a server within the tree.

Either the server name or one of the following special values must be specified:

*ANY	Use any server within the specified NDS tree.
*ALL	Start connections to all servers in the specified tree.

User profile name. The i5/OS user profile name that is authorized to use this connection.

The following special value may be used:

*CURRENT

Jobs running under the current user profile are authorized to use the connection.

Error Messages

Message ID	Error Message Text
CPF2144 E	Not authorized to &1 in &2 type *&3.
CPF2217 E	Not authorized to user profile &1.
CPF24B4 E	Severe error while addressing parameter list.
CPF3C1D E	Length specified in parameter &1 not valid.
CPF3C21 E	Format name &1 is not valid.
CPF3C90 E	Literal value cannot be changed.
CPF3CF1 E	Error code parameter not valid.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
FPE0211 E	Parameter length &1 not valid for field &2.
FPE0212 E	Field offset and length not within data.
FPE0215 E	Could not find authentication entry for &1.
FPE021C E	Not able to contact server &1.
FPE0227 E	Server name ANY or ALL not allowed for server type.
FPE0230 E	Connection type -1 must be single value.
FPE0235 E	Error &2 connecting to server &3.
FPE0236 E	Value &1 not valid for authorized job.
FPE0237 E	Value &1 not valid for connection idle time.
FPE023C E	Server is not a &2 server. Server: &1.
FPE023D E	NDS tree not known to system. Tree: &1.
FPE023E E	Server &1 not found in tree &2.

API introduced: V3R7

Top | Security APIs | APIs by category