(PYVMS LOGO) Python on OpenVMS

(go to: table of contents, index, list of vms_sys, prev: ENQW, next: FIND_HELD)


FILESCAN - Scan String for File Specification


Searches a string for a file specification and parses the components of that file specification.

vms_sys.filescan() does _not_ raise an exception when the SYS$FILESCAN routine returns an error. You must check 'status' in the dictionary that is returned.

Format:

    dict = vms_sys.filescan (srcstr, valuelst)\n\
Returns:
dict
A dictionary that has the following keys:
'status'
The condition value returned from SYS$FILESCAN.
'fldflags'
A 32-bit mask to which SYS$FILESCAN sets a bit for each file specification component found in the input string. Bitmask values (FSCN_M_name) for this field are located in module 'vms_fscndef'.

Note: the system services reference manual (OpenVMS VAX V6.1) names these bits as 'FSCN$V_name' - these are bit-offset values, which are not available within Python.

It is only put into the dictionary, when SYS$FILESCAN returns a success status.

'FSCN$_name'
Any output items that have been specified in the item-list and whose components could be located by SYS$FILESCAN.

The Python interface always specifies an 'auxout' buffer that is 65535 characters big to the SYS$FILESCAN system service.

It is only put into the dictionary, when SYS$FILESCAN returns a success status.

Arguments:
srcstr
String to be searched for the file specification.
valuelst
A tuple of strings in the form ('FSCN$_name1', 'FSCN$_name2', ...). Each item specifies a component that is to be returned by SYS$FILESCAN.

Items that the system service could not locate will not be returned in the dictionary ('dict').

Examples:
>>> import vms_sys
>>> import vms_fscndef

>>> srcstr   = 'NODNAM::DEV_STR:[UFD.SD]NAM.TYP;VER'
>>> valuelst = ('FSCN$_NODE', 'FSCN$_NAME', 'FSCN$_TYPE')
>>> dict     = vms_sys.filescan (srcstr, valuelst)

>>> # check if service completed successfully
>>> status   = dict.get ('status')
>>> status
1
>>> vms_sys.getmsg (status)
('%SYSTEM-S-NORMAL, normal successful completion', (0, 0, 0, 0))
>>>

>>> # show contents of the dictionary that was returned
>>> for key in dict.keys():
...   key, dict.get (key)
...
('FSCN$_NODE', 'NODNAM::')
('FSCN$_NAME', 'NAM')
('FSCN$_TYPE', '.TYP')
('fldflags', 251)
('status', 1)
>>>

>>> # this shows which components are PRESENT in the source string
>>> #   can be more than those that have been requested by 'valuelst'
>>> fldflags = dict.get ('fldflags')
>>> fldflags & vms_fscndef.FSCN_M_NODE
1
>>> fldflags & vms_fscndef.FSCN_M_NODE_PRIMARY
128
>>> fldflags & vms_fscndef.FSCN_M_NODE_ACS
0
>>> fldflags & vms_fscndef.FSCN_M_NODE_SECONDARY
0
>>> fldflags & vms_fscndef.FSCN_M_ROOT
0
>>> fldflags & vms_fscndef.FSCN_M_DEVICE
2
>>> fldflags & vms_fscndef.FSCN_M_DIRECTORY
8
>>> fldflags & vms_fscndef.FSCN_M_NAME
16
>>> fldflags & vms_fscndef.FSCN_M_TYPE
32
>>> fldflags & vms_fscndef.FSCN_M_VERSION
64
>>>

----------------------------------------

>>> # a single-item tuple --v
>>> valuelst = ('FSCN$__BAD', )
>>> dict     = vms_sys.filescan ('X', valuelst)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
ValueError: argument 2: valuelst - unknown item code: FSCN$__BAD
>>>

>>> # need string for item code ------------v
>>> valuelst = ('FSCN$_NODE', 'FSCN$_TYPE', 999)
>>> dict     = vms_sys.filescan ('X', valuelst)
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 2: valuelst - item:2 is not a string
>>> #                                  ^
>>> # The first index in a tuple is number 0

>>> dict = vms_sys.filescan ('X')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: function requires exactly 2 arguments; 1 given
>>>

>>> dict = vms_sys.filescan ('X','Y')
Traceback (innermost last):
  File "<stdin>", line 1, in ?
TypeError: argument 2: valuelst - must be a tuple of strings
>>>

----------------------------------------

@@ more examples for FILESCAN

(go to: table of contents, index, list of vms_sys, prev: ENQW, next: FIND_HELD)

24-MAR-1999 ZE.