USE [Elyse_DB]
GO
/****** Object:  StoredProcedure [controlling].[usp_INS_people_list_name]    Script Date: Fri 02-10-2026 8:29:39 PM ******/
SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER ON
GO
-- =============================================
-- Author:		Silkwood Software
-- Create date: 08-01-2024
-- Description:	Initial creation
-- Inserts a record into people.people_list_names to create a people list name
-- Input is mnemonic, name and description 
-- Output is a status message, transaction status and new record id.  
/*
COPYRIGHT NOTICE
This database schema and stored procedures are protected by copyright.
Copyright.  Silkwood Software Pty. Ltd. 2023
*/
-- =============================================
/**
* Inserts a record into people.people_list_names to create a people list name
* 
* **Acceptable Inputs:**
*
* - @mnemonic nvarchar(10): Can be null.
* - @peoplelist_name nvarchar(50): Must be a non-null and non-empty valid identifier which is unique.
* - @description nvarchar(max): Can be null.
*
*
* **Return Values:**
*
* - @message nvarchar(1000) OUTPUT: Descriptive status message of the procedure's execution.
* - @transaction_status nchar(50) OUTPUT: Indicates the transaction status ('Good', 'Bad', or default 'Transaction not attempted').
* - @newrecordid bigint: Record id of the new record
*
* **Error and Exception Conditions:**
*
* - User Role Validation Fail: Returns 'No Permission' message.
* - Data Validation Fail: Returns messages for invalid input data.
*
* **Side Effects:**
*
* - Adds a new record to people.people_list_names 
*
* **Preconditions:**
*
* - The user executing the procedure must have the 'Controller' role.
* - @peoplelist_name must be unique
*
* **Postconditions:**
* - The procedure returns status messages indicating the outcome of the operation.
*
*/
-- =========================================================
CREATE PROCEDURE [controlling].[usp_INS_people_list_name] 

     @mnemonic nvarchar(10)           = '',             
	 @peoplelist_name nvarchar(50),
	 @description nvarchar(max)       = '', 
	 @message nvarchar(1000)          = '' OUTPUT,
	 @transaction_status nvarchar(50) = NULL OUTPUT,
	 @newrecordid bigint              = NULL OUTPUT


AS
BEGIN
	-- SET NOCOUNT ON added to prevent extra result sets from
	-- interfering with SELECT statements.
	SET NOCOUNT ON;

  DECLARE 
        @tempmessage nvarchar(300)           = '',
		@tempuserauth_status nchar(10)       = '',
	    @connectedusersid varbinary(100)     = SUSER_SID(ORIGINAL_LOGIN()),   -- The SID of the connected user
	    @username nvarchar(150)              = ORIGINAL_LOGIN(),     -- The username 
	    @validationmessage nvarchar(200)     = '', -- Communicates that the transaction failed due to data validation
		@userauthentication_status nchar(10) = 'Fail', -- The outcome of the authentication check of the user 
		@tempvalidationstatus nchar(10)      = '',
		@transaction_ready nchar(10)         = 'Ready',
		@data_validation_status nchar(10)    = 'Pass';


  -- Parameters which have been initialised at declaration but not explicitly set might be output as null to calling functions.
  SET @transaction_status = 'Transaction not attempted';  
	 
  -- Connected user authentication
  -- Authenticate the connected user for the role
  EXEC [internal].[usp_AUTHENTICATE_user_role] 
        @role_to_check = 'Controller',
		@user_authentication_result = @userauthentication_status OUTPUT;
  IF @userauthentication_status = 'Fail'
    BEGIN  -- The user does not have permission for this action
		SET @transaction_ready      = 'Fail';
	    EXEC internal.usp_SEL_message 
            @message_id   = 'NoPermission', 
			@message_text = @tempmessage OUTPUT;
	    IF (@tempmessage IS NOT NULL) 
  	       SET @message = CONCAT(@message, ' | ', ISNULL(@username, ''), '  ', @tempmessage);
	    ELSE 
		   SET  @message = CONCAT_WS(' | ', @message,'A database level message error occurred on NoPermission.');
	END

  IF @userauthentication_status = 'Pass' -- Don't do anything if the user is not authorised.
    BEGIN
	  -- Data validation

	  -- Attribute name must be unique
	  IF EXISTS (SELECT pln.name
				   FROM people.people_list_names AS pln
				  WHERE pln.name = @peoplelist_name)
		   BEGIN
			 SET @data_validation_status = 'Fail';
			 SET @transaction_ready      = 'Fail';
			 EXEC internal.usp_SEL_message 
				  @message_id   = 'NameNotUnique', 
				  @message_text = @tempmessage OUTPUT;
			 IF @tempmessage IS NOT NULL 
  				SET @message = CONCAT(@message, ' | ', LEFT(@peoplelist_name, 10), '...  ',  @tempmessage);
			 ELSE 
				SET @message = CONCAT_WS(' | ', @message, 'A database level message error occurred on NameNotUnique.');
		   END

	  -- Perform generic data validation checks.  (Does not require access to the table.) 
			EXEC internal.usp_VALIDATE_mnem_name_descr
				@mnem             = @mnemonic,
				@attr_name        = @peoplelist_name,
				@descr            = @description,
				@data_valn_status = @tempvalidationstatus OUTPUT,
				@messg            = @validationmessage OUTPUT;
			IF @tempvalidationstatus = 'Fail'
				BEGIN
				  SET @message = CONCAT_WS(' |', @message, @validationmessage); 
				  SET @transaction_ready      = 'Fail';
				  SET @data_validation_status = 'Fail';
				END

	  -- Output the data validation status failed message
	  IF @data_validation_status = 'Fail'
		BEGIN
		  EXEC internal.usp_SEL_message 
			   @message_id   = 'FailedDataValidation', 
			   @message_text = @tempmessage OUTPUT;
		  IF (@tempmessage IS NOT NULL) 
  		    SET @message = CONCAT_WS(' | ', @message, @tempmessage);
		  ELSE 
		    SET @message = CONCAT_WS(' | ', @message, 'A database level message error occurred on FailedDataValidation');
		END
	  -- End data validation


-- Execute the insert query

  IF @transaction_ready = 'Ready'
	BEGIN
	  BEGIN TRY
	     INSERT INTO people.people_list_names
		             (mnem,                              name,           description)
		      VALUES (ISNULL(@mnemonic, ''), @peoplelist_name,   ISNULL(@description, '')); 
	  SET @newrecordid = SCOPE_IDENTITY();
         EXEC internal.usp_SEL_message 
              @message_id   = 'Success', 
              @message_text = @tempmessage OUTPUT;
  	     IF (@tempmessage IS NOT NULL) 
  		    SET @message = CONCAT_WS(' | ', @message, @tempmessage);
		  ELSE 
		    SET @message = CONCAT_WS(' | ', @message, 'A database level message error occurred on Success');
		 SET @transaction_status = 'Good';
   	  END TRY
	  BEGIN CATCH

	     IF XACT_STATE() <> 0
            ROLLBACK TRANSACTION;

	     SET @transaction_status = 'Bad';
         EXEC internal.usp_SEL_message 
              @message_id   = 'InsertError', 
              @message_text = @tempmessage OUTPUT;
		 IF (@tempmessage IS NOT NULL) 
		    SET @message = CONCAT(@message, ' | ', @tempmessage, ' | ', 
		    CONVERT(nvarchar(10),ERROR_NUMBER()), ' | ', ERROR_MESSAGE());
		 ELSE 
		    SET @message = CONCAT_WS(' | ', @message, 'A database level message error occurred on InsertError');
	  END CATCH
    END



 END -- End IF @userauthentication = 'Pass'


END
GO