pearl-elog.ipf File Reference
ARPES package

interface for writing ELOG entries with Igor graphs as attachment. More...

Go to the source code of this file.

## Namespaces

| PearlElog
| interface for writing ELOG entries with Igor graphs as attachment.

## Functions

variable | pearl_elog (string logbook)
| main function to initialize ELOG and to open an ELOG panel. More...
static variable | IgorBeforeNewHook (string igorApplicationNameStr)
| save preferences and recent values before Igor opens a new experiment. More...
static variable | IgorQuitHook (string igorApplicationNameStr)
| save preferences and recent values before Igor quits. More...
static variable | AfterFileOpenHook (variable refNum, string file, string pathName, string type, string creator, variable kind)
| initialize the package and reload preferences after an experiment is loaded. More...
static dfr | get_elog_df (string name, variable category)
| get the package, logbook, or template datafolder. More...
static variable | init_package (variable clean=defaultValue)
| initialize the package data folder. More...
variable | elog_init_pearl_templates ()
| setup PEARL template logbooks. More...
static variable | init_volatile_vars ()
| initialize volatile variables. More...
variable | elog_create_logbook (string name, string template=defaultValue)
| create a new logbook. More...
variable | elog_config (string elog_path=defaultValue, string hostname=defaultValue, variable port=defaultValue, string subdir=defaultValue)
| set global module configuration parameters More...
variable | elog_login (string logbook, string username, string password)
| set username and password for login to a logbook More...
variable | elog_logout (string logbook)
| clear username and password of a logbook or all logbooks. More...
static variable | save_prefs ()
| save persistent package data to the preferences file. More...
static variable | load_prefs ()
| load persistent package data from the preferences file. More...
static string | list_logbooks (variable templates=defaultValue)
| get a list of configured logbooks or templates. More...
variable | elog_validate_attributes (string logbook, string attributes)
| validate attributes More...
variable | elog_create_entry (string logbook, string attributes, string message, variable encoding=defaultValue, string graphs=defaultValue, variable replyto=defaultValue)
| create a new entry in ELOG More...
variable | elog_add_attachment (string logbook, variable id, string graphs)
| add one or more graphs to an existing ELOG entry More...
static string | prepare_command_line (string logbook)
| format the ELOG command and essential address arguments. More...
static string | format_url (string logbook)
| format the URL for display to the user More...
static string | prepare_graph_attachments (string graphs)
| prepare screenshots of graph windows for attachments More...
static string | get_timestamp (string sep)
static string | create_message_file (string message)
| save the message to a temporary text file More...
static string | create_graph_file (string graphname, variable fileindex)
| save a graph to a temporary graphics file More...
static string | create_cmd_file (string cmd)
| write the command line to a file. More...
static string | get_log_path ()
static variable | cleanup_temp_files ()
| delete temporary files created by the ELOG module. More...
static variable | parse_result ()
| parse the result file from an elog invokation. More...
string | elog_prompt_logbook ()
| prompt to open or create a logbook More...
variable | elog_prompt_login (string logbook)
| prompt the user for login to a logbook More...
string | PearlElogPanel (string logbook)
| open a new panel for submitting data to ELOG. More...
static variable | elog_panel_hook (WMWinHookStruct *s)
static variable | update_attach_items (string logbook)
| update the list of attachments More...
static variable | move_attach_item (string logbook, variable item, variable distance)
| move an attachment item in the list of attachments More...
static variable | bp_attach_updown (WMButtonAction *ba)
| button procedure for the attachment up and down buttons More...
static variable | bp_submit (WMButtonAction *ba)
| button procedure for the Submit and Reply buttons More...
static variable | bp_attach_top (WMButtonAction *ba)
| select top graph window for attachment More...
static variable | bp_attach_allnone (WMButtonAction *ba)
| select/deselect all graph windows for attachment More...
static variable | bp_attach (WMButtonAction *ba)
static variable | bp_save_graphs (WMButtonAction *ba)
static variable | bp_clear (WMButtonAction *ba)
static variable | bp_login (WMButtonAction *ba)
static variable | bp_logout (WMButtonAction *ba)
static string | get_default_panel_name ()
static string | get_panel_attributes (string windowname)
| get a list of attributes from the fields of the ELOG panel. More...
static string | set_panel_attributes (string windowname, string attributes, variable clear=defaultValue)
| set the fields of the ELOG panel More...
static string | get_panel_message (string windowname)
| get the message field of the ELOG panel More...
static string | set_panel_message (string windowname, string message)
| set the message field of the ELOG panel More...
static string | get_panel_graphs (string windowname)
| get the names of the graphs selected for attachment More...
static string | set_panel_graphs (string windowname, string graphs)
| update selection of graphs for attachment More...

## Variables

static const string | package_name = "pearl_elog"
static const string | package_path = "root:packages:pearl_elog:"
static const variable | kdfRoot = 0
static const variable | kdfVolatile = 1
static const variable | kdfPersistent = 2
static const variable | kdfTemplates = 3
static const string | elog_success_msg = "Message successfully transmitted"
static const string | elog_parse_id = "ID=%u"
static const variable | kAttachColSel = 0
static const variable | kAttachColTitle = 1
static const variable | kAttachColName = 2

## Detailed Description

interface for writing ELOG entries with Igor graphs as attachment.

the functions in this module support the following ELOG features:

- submit new entries and replies to existing entries.
- text field, list box, and check box attributes.
- attach any Igor graph to ELOG.
- configurable logbook templates for logbooks that share the same configuration.
- common server configurations available on the ELOG command line (hostname, port, SSL, username, password, sub-directory).
- not specific to the configuration at PEARL. PEARL code is concentrated in the elog_init_pearl_templates() function.
- the configuration of the ELOG server and logbooks as well as the most recently used attributes are persisted in the preference file.

usage:

1. the administrator of the ELOG server creates logbook templates according to the configuration of the logbooks. the templates are written in Igor code.
2. the user opens logbooks via the Open ELOG panel menu item. before first use, select a template and enter a name for the logbook. the new logbook is written to the preference file, and can afterwards be opened directly.
3. if the server requires a user name and password, click the login button.
4. edit the message, attributes and attachments as necessary, and submit to ELOG.
5. log out before saving the experiment to clear the password.

Attention
  the user name and password are stored in the global data tree of an experiment. it is not possible to handle passwords safely in Igor. they can be read by anyone having access to an open Igor experiment or a saved experiment file (unless the password is reset before saving). therefore:
  - use a password for the ELOG server which is different from your other passwords.
  - clear the password (logout button in the panel) before saving an experiment.

elog command line

    *  elog -h <hostname> [-p port] [-d subdir]
    *                               Location where elogd is running
    *      -l logbook               Name of logbook
    *      -s                       Use SSL for communication
    *      [-v]                     For verbose output
    *      [-w password]            Write password defined on server
    *      [-u username password]   User name and password
    *      [-f <attachment>]        Up to 50 attachments
    *      -a <attribute>=<value>   Up to 50 attributes
    *      [-r <id>]                Reply to existing message
    *      [-q]                     Quote original text on reply
    *      [-e <id>]                Edit existing message
    *      [-x]                     Suppress email notification
    *      [-n 0|1|2]               Encoding: 0:ELcode,1:plain,2:HTML
    *      -m <textfile>] | <text>
    *

Author
  matthias muntwiler, matth.nosp@m.ias..nosp@m.muntw.nosp@m.iler.nosp@m.@psi..nosp@m.ch

Copyright
  2013-17 Paul Scherrer Institut
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Definition in file pearl-elog.ipf.

## Function Documentation

## AfterFileOpenHook()

static variable AfterFileOpenHook | ( | variable | refNum,
|  | string | file,
|  | string | pathName,
|  | string | type,
|  | string | creator,
|  | variable | kind
| ) |  |

static

initialize the package and reload preferences after an experiment is loaded.

Definition at line 143 of file pearl-elog.ipf.

## bp_attach()

static variable bp_attach | ( | WMButtonAction * | ba | ) |

static

Definition at line 1634 of file pearl-elog.ipf.

## bp_attach_allnone()

static variable bp_attach_allnone | ( | WMButtonAction * | ba | ) |

static

select/deselect all graph windows for attachment

Definition at line 1613 of file pearl-elog.ipf.

## bp_attach_top()

static variable bp_attach_top | ( | WMButtonAction * | ba | ) |

static

select top graph window for attachment

Definition at line 1597 of file pearl-elog.ipf.

## bp_attach_updown()

static variable bp_attach_updown | ( | WMButtonAction * | ba | ) |

static

button procedure for the attachment up and down buttons

Definition at line 1518 of file pearl-elog.ipf.

## bp_clear()

static variable bp_clear | ( | WMButtonAction * | ba | ) |

static

Definition at line 1695 of file pearl-elog.ipf.

## bp_login()

static variable bp_login | ( | WMButtonAction * | ba | ) |

static

Definition at line 1711 of file pearl-elog.ipf.

## bp_logout()

static variable bp_logout | ( | WMButtonAction * | ba | ) |

static

Definition at line 1729 of file pearl-elog.ipf.

## bp_save_graphs()

static variable bp_save_graphs | ( | WMButtonAction * | ba | ) |

static

Definition at line 1667 of file pearl-elog.ipf.

## bp_submit()

static variable bp_submit | ( | WMButtonAction * | ba | ) |

static

button procedure for the Submit and Reply buttons

Definition at line 1550 of file pearl-elog.ipf.

## cleanup_temp_files()

static variable cleanup_temp_files | ( |  | ) |

static

delete temporary files created by the ELOG module.

this deletes all temporary graph files that are referenced by the volatile temp_graph_files list. temp_graph_files is a semicolon-delimited string. items are added by create_graph_file().

this function should be called before a new experiment is loaded or igor quits.

Definition at line 1115 of file pearl-elog.ipf.

## create_cmd_file()

static string create_cmd_file | ( | string | cmd | ) |

static

write the command line to a file.

the command script changes the working directory to the Temporary directory. it also deletes a previous elog.log file.

Note
  somewhere the command line (even inside command files) is limited to 1024 bytes. for this reason all files should now be in the Temporary directory assigned by igor.

Definition at line 1059 of file pearl-elog.ipf.

## create_graph_file()

static string create_graph_file | ( | string | graphname,
|  | variable | fileindex
| ) |  |

static

save a graph to a temporary graphics file

the file is saved to the Temporary directory returned by igor's SpecialDirPath function. the file name contains a time stamp and the specified file index to make it unique. the function returns the name of the file (excluding path!)

the full path is added to the temp_graph_files global list. a hook function will delete the files listed there when igor quits.

Parameters

  graphname | object name of the graph to save.
  fileindex | incrememtal index of the file within one submission. the file name is made unique by a time stamp and this file index. submissions within the same second must have a unique file index.

Returns
  (string) name of the created file. empty string if unsuccessful.

Version
  1.41 the return value has changed from full path to file name only due to the limited length of the command line (1024 bytes).

Definition at line 1023 of file pearl-elog.ipf.

## create_message_file()

static string create_message_file | ( | string | message | ) |

static

save the message to a temporary text file

the file is saved to the Temporary directory returned by igor's SpecialDirPath function under the file name "elog_temp_message.txt". the function returns the name of the file (excluding path!)

Note
  percent characters (%) cannot be passed to elog. they are removed silently from the message.

Parameters

  message | text message to save to the file.

Returns
  (string) name of the created file. empty string if unsuccessful.

Version
  1.41 the return value has changed from full path to file name only due to the limited length of the command line (1024 bytes).

Definition at line 982 of file pearl-elog.ipf.

## elog_add_attachment()

variable elog_add_attachment | ( | string | logbook,
|  | variable | id,
|  | string | graphs
| ) |  |

add one or more graphs to an existing ELOG entry

Parameters

  logbook | name of the target logbook
  id | identification number of the existing entry
  graphs | names of graph windows to be added as attachments, semicolon separated

Warning
  this will delete all existing attachments of the entry!

Definition at line 792 of file pearl-elog.ipf.

## elog_config()

variable elog_config | ( | string | elog_path = `defaultValue`,
|  | string | hostname = `defaultValue`,
|  | variable | port = `defaultValue`,
|  | string | subdir = `defaultValue`
| ) |  |

set global module configuration parameters

Definition at line 473 of file pearl-elog.ipf.

## elog_create_entry()

variable elog_create_entry | ( | string | logbook,
|  | string | attributes,
|  | string | message,
|  | variable | encoding = `defaultValue`,
|  | string | graphs = `defaultValue`,
|  | variable | replyto = `defaultValue`
| ) |  |

create a new entry in ELOG

this is the main function to create a new entry in a logbook.

Parameters

  logbook | name of the target logbook.
  attributes | key=value list of attributes, semicolon separated.
  message | free text part of the entry.
  encoding | encoding of message, 0:ELcode, 1:plain (default), 2:HTML.
  graphs | names of graph windows to be added as attachments, semicolon separated.
  replyto | existing message ID (> 1) to follow up on. 0 or default: start new thread.

Returns
  ID number of the new entry (> 0), or error code (< 0).
  - -1: failed to save temporary message file.
  - -2: invalid/missing command line.
  - -3: invalid/missing attributes.
  - -4: elog returned error

Definition at line 685 of file pearl-elog.ipf.

## elog_create_logbook()

variable elog_create_logbook | ( | string | name,
|  | string | template = `defaultValue`
| ) |  |

create a new logbook.

create a new empty logbook or duplicate from a template.

Parameters

  name | name of the new logbook. if the logbook exists, the existing logbook folder is killed and replaced by a new one. this may fail if a window is still open.
  template | name of the template. if empty string, a new empty logbook is created.

Definition at line 414 of file pearl-elog.ipf.

## elog_init_pearl_templates()

variable elog_init_pearl_templates | ( |  | ) |

setup PEARL template logbooks.

template logbooks for PEARL.

Remarks
  this function is specific to the setup at PEARL.

Definition at line 262 of file pearl-elog.ipf.

## elog_login()

variable elog_login | ( | string | logbook,
|  | string | username,
|  | string | password
| ) |  |

set username and password for login to a logbook

the username and password are stored (in plain text) in global strings under the selected logbook folder. this is necessary for sending data to the ELOG server.

call elog_logout() to clear the password variables and to avoid unintended use of your credentials.

Warning
  igor does not have a built-in mechanism to protect passwords. user names and passwords are stored in plain text in the data folder tree. as such they are saved to experiment files and preferences.

Parameters

  logbook | name of the target logbook.

Definition at line 513 of file pearl-elog.ipf.

## elog_logout()

variable elog_logout | ( | string | logbook | ) |

clear username and password of a logbook or all logbooks.

the username and password are stored (in plain text) in global strings under the selected logbook folder. this function resets the username and password strings.

Parameters

  logbook | name of the target logbook. if empty, the passwords of all logbooks are cleared.

Definition at line 533 of file pearl-elog.ipf.

## elog_panel_hook()

static variable elog_panel_hook | ( | WMWinHookStruct * | s | ) |

static

Definition at line 1394 of file pearl-elog.ipf.

## elog_prompt_logbook()

string elog_prompt_logbook | ( |  | ) |

prompt to open or create a logbook

Definition at line 1184 of file pearl-elog.ipf.

## elog_prompt_login()

variable elog_prompt_login | ( | string | logbook | ) |

prompt the user for login to a logbook

Definition at line 1214 of file pearl-elog.ipf.

## elog_validate_attributes()

variable elog_validate_attributes | ( | string | logbook,
|  | string | attributes
| ) |  |

validate attributes

Returns
  0 if all required attributes are present and enumerated items are correct. non-zero if a violation is detected.

Todo:
  function currently not implemented, always returns 0

Definition at line 653 of file pearl-elog.ipf.

## format_url()

static string format_url | ( | string | logbook | ) |

static

format the URL for display to the user

Parameters

  logbook | name of the target logbook

Definition at line 902 of file pearl-elog.ipf.

## get_default_panel_name()

static string get_default_panel_name | ( |  | ) |

static

Definition at line 1746 of file pearl-elog.ipf.

## get_elog_df()

static dfr get_elog_df | ( | string | name,
|  | variable | category
| ) |  |

static

get the package, logbook, or template datafolder.

Parameters

  name | name of logbook or template, or empty string for respective parent folder.

  category

  parameter category:
  - kdfRoot package root
  - kdfVolatile volatile
  - kdfPersistent persistent
  - kdfTemplates template

Returns
  data folder reference

Definition at line 170 of file pearl-elog.ipf.

## get_log_path()

static string get_log_path | ( |  | ) |

static

Definition at line 1095 of file pearl-elog.ipf.

## get_panel_attributes()

static string get_panel_attributes | ( | string | windowname | ) |

static

get a list of attributes from the fields of the ELOG panel.

Parameters

  windowname | window name of the ELOG panel if empty, use default name "PearlElogPanel"

Returns
  list of attributes to in the format `"key1=value1;key2=value2"`.

Definition at line 1759 of file pearl-elog.ipf.

## get_panel_graphs()

static string get_panel_graphs | ( | string | windowname | ) |

static

get the names of the graphs selected for attachment

Parameters

  windowname | panel window name

Returns
  a semicolon-separated list, or the empty string if the selection is not valid.

Definition at line 1914 of file pearl-elog.ipf.

## get_panel_message()

static string get_panel_message | ( | string | windowname | ) |

static

get the message field of the ELOG panel

Parameters

  windowname | window name of the ELOG panel if empty, use default name "PearlElogPanel"

Returns
  message text

Definition at line 1868 of file pearl-elog.ipf.

## get_timestamp()

static string get_timestamp | ( | string | sep | ) |

static

Definition at line 958 of file pearl-elog.ipf.

## IgorBeforeNewHook()

static variable IgorBeforeNewHook | ( | string | igorApplicationNameStr | ) |

static

save preferences and recent values before Igor opens a new experiment.

Definition at line 127 of file pearl-elog.ipf.

## IgorQuitHook()

static variable IgorQuitHook | ( | string | igorApplicationNameStr | ) |

static

save preferences and recent values before Igor quits.

Definition at line 135 of file pearl-elog.ipf.

## init_package()

static variable init_package | ( | variable | clean = `defaultValue` | ) |

static

initialize the package data folder.

the data folder is initialized with a default, local configuration without any logbooks. the server configuration should be set in the preferences.

Parameters

  clean

  decides what to do if the package configuration exists.
  - 0 (default) keep existing configuration.
  - 1 overwrite existing configuration.

Definition at line 217 of file pearl-elog.ipf.

## init_volatile_vars()

static variable init_volatile_vars | ( |  | ) |

static

initialize volatile variables.

create and initialize all volatile variables for the configured notebooks. values of existing variables are not changed.

this function must be called after new logbooks have been configured, specifically by elog_create_logbook() and load_prefs().

Definition at line 340 of file pearl-elog.ipf.

## list_logbooks()

static string list_logbooks | ( | variable | templates = `defaultValue` | ) |

static

get a list of configured logbooks or templates.

this is list of data folder names under persistent:logbooks (or persistent:templates). the function does not check whether the folders contain valid data.

Parameters

  templates | select whether logbooks (0, default) or templates (1) are returned.

Returns
  semicolon-separated list of logbooks

Definition at line 618 of file pearl-elog.ipf.

## load_prefs()

static variable load_prefs | ( |  | ) |

static

load persistent package data from the preferences file.

the preferences file is an Igor packed experiment file in a special preferences folder

Definition at line 584 of file pearl-elog.ipf.

## move_attach_item()

static variable move_attach_item | ( | string | logbook,
|  | variable | item,
|  | variable | distance
| ) |  |

static

move an attachment item in the list of attachments

Definition at line 1494 of file pearl-elog.ipf.

## parse_result()

static variable parse_result | ( |  | ) |

static

parse the result file from an elog invokation.

Returns
  the ID of the generated message, or a value <= 0 if an error occurred.

Definition at line 1141 of file pearl-elog.ipf.

## pearl_elog()

variable pearl_elog | ( | string | logbook | ) |

main function to initialize ELOG and to open an ELOG panel.

this function takes care of all necessary initialization, configuration, and preferences. if a panel exists, it will be moved to the front.

Parameters

  logbook | name of the logbook if empty, the user is prompted to select or create a logbook by elog_prompt_logbook().

Definition at line 97 of file pearl-elog.ipf.

## PearlElogPanel()

string PearlElogPanel | ( | string | logbook | ) |

open a new panel for submitting data to ELOG.

this function creates only the panel but not the necessary data folders. call init_package() and load_prefs() once before creating panels.

Parameters

  logbook | name of the target logbook

Definition at line 1241 of file pearl-elog.ipf.

## prepare_command_line()

static string prepare_command_line | ( | string | logbook | ) |

static

format the ELOG command and essential address arguments.

the following arguments are included (from global variables) if applicable: host name, port, SSL, sub-dir, username, password the result string does not include leading or trailing space

Parameters

  logbook | name of the target logbook

Definition at line 853 of file pearl-elog.ipf.

## prepare_graph_attachments()

static string prepare_graph_attachments | ( | string | graphs | ) |

static

prepare screenshots of graph windows for attachments

prepares the attachment files from Igor graph windows and returns the arguments to the elog command to attach the files. file names are returned without path. the result string does not include leading or trailing space.

Parameters

  graphs | names of graph windows to be added as attachments, semicolon separated

Definition at line 939 of file pearl-elog.ipf.

## save_prefs()

static variable save_prefs | ( |  | ) |

static

save persistent package data to the preferences file.

saves everything under the persistent folder of the package.

Definition at line 564 of file pearl-elog.ipf.

## set_panel_attributes()

static string set_panel_attributes | ( | string | windowname,
|  | string | attributes,
|  | variable | clear = `defaultValue`
| ) |  |

static

set the fields of the ELOG panel

Parameters

  windowname | window name of the ELOG panel if empty, use default name "PearlElogPanel"
  attributes | list of attributes to set (format "key1=value1;key2=value2")

  clear

  what to do if a key is missing in attributes?
  - 0 (default) leave the field unchanged
  - 1 clear the field

Definition at line 1806 of file pearl-elog.ipf.

## set_panel_graphs()

static string set_panel_graphs | ( | string | windowname,
|  | string | graphs
| ) |  |

static

update selection of graphs for attachment

Parameters

  windowname | panel window name. looks for default panel if empty.
  graphs | semicolon-separated list of names of graph windows to select for attachment.

Definition at line 1954 of file pearl-elog.ipf.

## set_panel_message()

static string set_panel_message | ( | string | windowname,
|  | string | message
| ) |  |

static

set the message field of the ELOG panel

Parameters

  windowname | window name of the ELOG panel if empty, use default name "PearlElogPanel"
  message | message text that can be passed to the `Notebook` operation.

Returns
  original message (unchanged)

Definition at line 1894 of file pearl-elog.ipf.

## update_attach_items()

static variable update_attach_items | ( | string | logbook | ) |

static

update the list of attachments

Definition at line 1433 of file pearl-elog.ipf.

## Variable Documentation

## elog_parse_id

const string elog_parse_id = "ID=%u"

static

Definition at line 1134 of file pearl-elog.ipf.

## elog_success_msg

const string elog_success_msg = "Message successfully transmitted"

static

Definition at line 1133 of file pearl-elog.ipf.

## kAttachColName

const variable kAttachColName = 2

static

Definition at line 1430 of file pearl-elog.ipf.

## kAttachColSel

const variable kAttachColSel = 0

static

Definition at line 1428 of file pearl-elog.ipf.

## kAttachColTitle

const variable kAttachColTitle = 1

static

Definition at line 1429 of file pearl-elog.ipf.

## kdfPersistent

const variable kdfPersistent = 2

static

Definition at line 155 of file pearl-elog.ipf.

## kdfRoot

const variable kdfRoot = 0

static

Definition at line 153 of file pearl-elog.ipf.

## kdfTemplates

const variable kdfTemplates = 3

static

Definition at line 156 of file pearl-elog.ipf.

## kdfVolatile

const variable kdfVolatile = 1

static

Definition at line 154 of file pearl-elog.ipf.

## package_name

const string package_name = "pearl_elog"

static

Definition at line 85 of file pearl-elog.ipf.

## package_path

const string package_path = "root:packages:pearl_elog:"

static

Definition at line 86 of file pearl-elog.ipf.