HSLFilLib.rst

HSLFilLib

https://github.com/theonetruenerd/VenusPackages/blob/main/HSLFilLib.pkg

This library allows interaction with and manipulation of files present on the host computer. It adds the following functions:

• :py:func:`FilEof`
• :py:func:`FilFindFile`
• :py:func:`FilFindNextFile`
• :py:func:`FilFormatBarcodeFile`
• :py:func:`FilGetBinPath`
• :py:func:`FilGetCommState`
• :py:func:`FilGetCommTimeouts`
• :py:func:`FilGetConfigPath`
• :py:func:`FilGetLabwarePath`
• :py:func:`FilGetLibraryPath`
• :py:func:`FilGetLogFilesPath`
• :py:func:`FilGetMethodsPath`
• :py:func:`FilGetSystemPath`
• :py:func:`FilIsNull`
• :py:func:`FilReadString`
• :py:func:`FilRemoveFields`
• :py:func:`FilSearchPath`
• :py:func:`FilSetCommState`
• :py:func:`FilSetCommTimeouts`
• :py:func:`FilUpdateRecord`
• :py:func:`FilWriteString`

.. py:function:: FilEof(variable filObj)

  This function checks whether the current position in the specified file is the final line

  :params filObj: The opened file to be checked
  :type filObj: Variable (file)
  :return: Boolean as to whether the position is the end of the file or not
  :rtype: Boolean

.. py:function:: FilFindFile(variable filName)

  This function starts searching the specified path for a file. This function is obsolete, and :py:func:`FilSearchPath` should be used instead.

  :params filName: The directory or path and file name to be searched for. Can contain wildcard characters such as * or ?
  :type filName: Variable
  :return: If successful, the path name of the first file found that matches the input
  :rtype: Variable

.. py:function:: FilFindNextFile()

  Continues the search from :py:func:`FilFindFile` to the next file.

  :return: If successful, the path name of the next file found that matches the input from the most recent FilFindFile command
  :rtype: Variable

.. py:function:: FilFormatBarcodeFile(variable dataSource, variable dataTarget)

  This function takes the barcode ASCII text file written during LoadCarrier and converts it into a strongly formatted barcode file. This strongly formatted file can be an ASCII text file, a Microsoft Excel file, or a Microsoft Access file. Will contain the following columns:

  - ID (record ID, integer)
  - Specifier (string, P = position, C = carrier)
  - Position (position, integer)
  - Barcode (barcode, string)
  - Timestamp (timestamp, YYYY-MM-DD hh:mm:ss, string)

  :params dataSource: The name of the barcode ASCII file generated during the load carrier step
  :params dataTarget: The name of the barcode ASCII text file, Microsoft Excel file or Microsoft Access file generated by the function. The name must include a table name for a Microsoft Excel file or a Microsoft Access Database.
  :type dataSource: Variable
  :type dataTarget: Variable
  :return: Boolean showing if the function was successful or not
  :rtype: Boolean

.. py:function:: FilGetBinPath()

  This function retrieves the vector binary path

  :return: The vectory binary path (usually C:\Program Files (x86)\Hamilton\Bin)
  :rtype: Variable

.. py:function:: FilGetCommState(file port)

  This function retrieves the configuration information for the specified communication resource. The entries of the structure that retrieves the configuration information must be accessible in the global scope.

  :params port: The communication resource opened during the file-Open operation
  :type: Port
  :return: Boolean showing if the function was successful or not
  :rtype: Boolean

.. py:function:: GetCommTimeouts(file port)

  This function retrieves the time-out parameters for all read and write operations for the specified communication resource. The entries of the structure that contains the configuration information must be accessible in the global scope.

  :params port: The communication resource opened during the file-Open operation
  :type port: Port
  :return: Boolean showing if the function was successful or not
  :rtype: Boolean

.. py:function:: FilGetConfigPath()

  This function retrieves the vector configuration path

  :return: The vector configuration path (usually C:\Program Files (x86)\Hamilton\Config)
  :rtype: Variable

.. py:function:: FilGetLabwarePath()

  This function retrieves the vector labware path

  :return: The vector labware path (usually C:\Program Files (x86)\Hamilton\Labware)
  :rtype: Variable

.. py:function:: FilGetLibraryPath()

  This function retrieves the vector library path

  :return: The vector library path (usually C:\Program Files (x86)\Hamilton\Library)
  :rtype: Variable

.. py:function:: FilGetLogFilesPath()

  This function retrieves the vector log files path

  :return: The vector log files path (usually C:\Program Files (x86)\Hamilton\LogFiles)
  :rtype: Variable

.. py:function:: FilGetMethodsPath()

  This function retrieves the vector methods path

  :return: The vector methods path (usually C:\Program Files (x86)\Hamilton\Methods)
  :rtype: Variable

.. py:function:: FilGetSystemPath()

  This function retrieves the vector system path

  :return: The vector system path (usually C:\Program Files (x86)\Hamilton\System)
  :rtype: Variable

.. py:function:: FilIsNull(variable value)

  This function returns a non-zero if the variable is a null value (SQL style Null).

  :params value: The variable being checked
  :type value: Variable
  :return: A boolean determining if the variable is SQL style Null or not
  :rtype: Boolean

.. py:function:: FilReadString(file fileObj)

  This function reads the next record from the input file as string-valued data. Row data, but no schema data, is saved to the string. After you call FilReadString, the next unread record becomes the current record, or Eof is set to hslTrue if there are no more records.

  :params fileObj: The file being looked at
  :type fileObj: File
  :return: The contents of the line being looked at as string-valued data, or the specific run-time error
  :rtype: String

.. py:function:: FilRemoveFields(file fileObj)

  This function removes all fields from a record definition

  :params fileObj: The file containing the record which is having its fields removed
  :type fileObj: File
  :return: None
  :rtype: N/A

.. py:function:: FilSearchPath(variable fileName)

  This function searches for the specified file, and outputs the path and filename of the file if found, or an empty string if not found. Will search the current directory, the methods directory, the library directory, and any directories in the PATH environment variable.

  :params fileName: The file name to be searched for
  :type fileName: Variable
  :return: The path name of the first file found, or an empty string if no files were found
  :rtype: Variable

.. py:function:: FilSetCommState(file port, variable cfgFile)

  This function configures a communication resource according to the specifications in a structure that contains the configuration information. The structure that contains the configuration information must be structured as shown below. Each entry in the structure is optional and overwrites the default value in parentheses.

  :params port: The communication resource opened during the file-Open operation
  :params cfgFile: The name of the file containing the configuration information. If this parameter is empty, the entries in the structure that contains the configuration information must be accessible in the global scope.
  :type port: File
  :type cfgFile: Variable
  :return: Boolean showing whether the function succeeded or not
  :rtype: Boolean

.. py:function:: FilSetCommTimeouts(file port, variable cfgFile)

  This function sets the time-out parameters for all read and write operations on a specified communication resource. The structure that contains the time-out information is as shown below. Each entry in the structure is optional and overwrites the default value in parentheses.

  :params port: The communication resource opened during the file-Open operation
  :params cfgFile: The name of the file that contains the time-out information. If this parameter is empty, the entries in the structure that contains the time-out information must be accessible in the global scope.
  :type port: File
  :type cfgFile: Variable
  :return: Boolean showing whether the function succeeded or not
  :rtype: Boolean

.. py:function:: FilUpdateRecord(file fileObj)

  Updates the current record of the file object with the values of the variable objects specified in the record definition. The current record remains current after you call the FilUpdateRecord function. The provider must support UPDATE.

  :params fileObj: The file object being updated
  :type fileObj: File
  :return: Boolean showing whether the function succeeded or not
  :rtype: Boolean

.. py:function:: FilWriteString(file fileObj, variable stringObj)

  Writes a string to the end of the file data source. After you call the FilWriteString function, the new record becomes the current record.

  :params fileObj: The file which is being written in
  :params stringObj: The string to be written
  :type fileObj: File
  :type stringObj: Variable
  :return: Boolean showing whether the function succeeded or not
  :rtype: Boolean